@office-ai/aioncli-core 0.30.0 → 0.30.1

package/dist/src/telemetry/trace.test.js

@@ -0,0 +1,116 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { trace, SpanStatusCode, diag } from '@opentelemetry/api';
+import { runInDevTraceSpan } from './trace.js';
+import { GeminiCliOperation, GEN_AI_CONVERSATION_ID, GEN_AI_AGENT_DESCRIPTION, GEN_AI_AGENT_NAME, GEN_AI_INPUT_MESSAGES, GEN_AI_OPERATION_NAME, GEN_AI_OUTPUT_MESSAGES, SERVICE_DESCRIPTION, SERVICE_NAME, } from './constants.js';
+vi.mock('@opentelemetry/api', async (importOriginal) => {
+    const original = await importOriginal();
+    return {
+        ...original,
+        trace: {
+            getTracer: vi.fn(),
+        },
+        diag: {
+            error: vi.fn(),
+        },
+    };
+});
+vi.mock('../utils/session.js', () => ({
+    sessionId: 'test-session-id',
+}));
+describe('runInDevTraceSpan', () => {
+    const mockSpan = {
+        setAttribute: vi.fn(),
+        setStatus: vi.fn(),
+        recordException: vi.fn(),
+        end: vi.fn(),
+    };
+    const mockTracer = {
+        startActiveSpan: vi.fn((name, options, callback) => callback(mockSpan)),
+    };
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.mocked(trace.getTracer).mockReturnValue(mockTracer);
+    });
+    afterEach(() => {
+        vi.unstubAllEnvs();
+    });
+    it('should start an active span', async () => {
+        const fn = vi.fn(async () => 'result');
+        const result = await runInDevTraceSpan({ operation: GeminiCliOperation.LLMCall }, fn);
+        expect(result).toBe('result');
+        expect(trace.getTracer).toHaveBeenCalled();
+        expect(mockTracer.startActiveSpan).toHaveBeenCalledWith(GeminiCliOperation.LLMCall, {}, expect.any(Function));
+    });
+    it('should set default attributes on the span metadata', async () => {
+        await runInDevTraceSpan({ operation: GeminiCliOperation.LLMCall }, async ({ metadata }) => {
+            expect(metadata.attributes[GEN_AI_OPERATION_NAME]).toBe(GeminiCliOperation.LLMCall);
+            expect(metadata.attributes[GEN_AI_AGENT_NAME]).toBe(SERVICE_NAME);
+            expect(metadata.attributes[GEN_AI_AGENT_DESCRIPTION]).toBe(SERVICE_DESCRIPTION);
+            expect(metadata.attributes[GEN_AI_CONVERSATION_ID]).toBe('test-session-id');
+        });
+    });
+    it('should set span attributes from metadata on completion', async () => {
+        await runInDevTraceSpan({ operation: GeminiCliOperation.LLMCall }, async ({ metadata }) => {
+            metadata.input = { query: 'hello' };
+            metadata.output = { response: 'world' };
+            metadata.attributes['custom.attr'] = 'value';
+        });
+        expect(mockSpan.setAttribute).toHaveBeenCalledWith(GEN_AI_INPUT_MESSAGES, JSON.stringify({ query: 'hello' }));
+        expect(mockSpan.setAttribute).toHaveBeenCalledWith(GEN_AI_OUTPUT_MESSAGES, JSON.stringify({ response: 'world' }));
+        expect(mockSpan.setAttribute).toHaveBeenCalledWith('custom.attr', 'value');
+        expect(mockSpan.setStatus).toHaveBeenCalledWith({
+            code: SpanStatusCode.OK,
+        });
+        expect(mockSpan.end).toHaveBeenCalled();
+    });
+    it('should handle errors in the wrapped function', async () => {
+        const error = new Error('test error');
+        await expect(runInDevTraceSpan({ operation: GeminiCliOperation.LLMCall }, async () => {
+            throw error;
+        })).rejects.toThrow(error);
+        expect(mockSpan.setStatus).toHaveBeenCalledWith({
+            code: SpanStatusCode.ERROR,
+            message: 'test error',
+        });
+        expect(mockSpan.recordException).toHaveBeenCalledWith(error);
+        expect(mockSpan.end).toHaveBeenCalled();
+    });
+    it('should respect noAutoEnd option', async () => {
+        let capturedEndSpan = () => { };
+        const result = await runInDevTraceSpan({ operation: GeminiCliOperation.LLMCall, noAutoEnd: true }, async ({ endSpan }) => {
+            capturedEndSpan = endSpan;
+            return 'streaming';
+        });
+        expect(result).toBe('streaming');
+        expect(mockSpan.end).not.toHaveBeenCalled();
+        capturedEndSpan();
+        expect(mockSpan.end).toHaveBeenCalled();
+    });
+    it('should automatically end span on error even if noAutoEnd is true', async () => {
+        const error = new Error('streaming error');
+        await expect(runInDevTraceSpan({ operation: GeminiCliOperation.LLMCall, noAutoEnd: true }, async () => {
+            throw error;
+        })).rejects.toThrow(error);
+        expect(mockSpan.end).toHaveBeenCalled();
+    });
+    it('should handle exceptions in endSpan gracefully', async () => {
+        mockSpan.setAttribute.mockImplementation(() => {
+            throw new Error('attribute error');
+        });
+        await runInDevTraceSpan({ operation: GeminiCliOperation.LLMCall }, async ({ metadata }) => {
+            metadata.input = 'trigger error';
+        });
+        expect(diag.error).toHaveBeenCalled();
+        expect(mockSpan.setStatus).toHaveBeenCalledWith(expect.objectContaining({
+            code: SpanStatusCode.ERROR,
+            message: expect.stringContaining('attribute error'),
+        }));
+        expect(mockSpan.end).toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=trace.test.js.map

package/dist/src/telemetry/trace.test.js.map

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

package/dist/src/tools/definitions/trackerTools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ToolDefinition } from './types.js';
+export declare const TRACKER_CREATE_TASK_DEFINITION: ToolDefinition;
+export declare const TRACKER_UPDATE_TASK_DEFINITION: ToolDefinition;
+export declare const TRACKER_GET_TASK_DEFINITION: ToolDefinition;
+export declare const TRACKER_LIST_TASKS_DEFINITION: ToolDefinition;
+export declare const TRACKER_ADD_DEPENDENCY_DEFINITION: ToolDefinition;
+export declare const TRACKER_VISUALIZE_DEFINITION: ToolDefinition;

package/dist/src/tools/definitions/trackerTools.js

@@ -0,0 +1,146 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TRACKER_CREATE_TASK_TOOL_NAME, TRACKER_UPDATE_TASK_TOOL_NAME, TRACKER_GET_TASK_TOOL_NAME, TRACKER_LIST_TASKS_TOOL_NAME, TRACKER_ADD_DEPENDENCY_TOOL_NAME, TRACKER_VISUALIZE_TOOL_NAME, } from '../tool-names.js';
+export const TRACKER_CREATE_TASK_DEFINITION = {
+    base: {
+        name: TRACKER_CREATE_TASK_TOOL_NAME,
+        description: 'Creates a new task in the tracker.',
+        parametersJsonSchema: {
+            type: 'object',
+            properties: {
+                title: {
+                    type: 'string',
+                    description: 'Short title of the task.',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Detailed description of the task.',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['epic', 'task', 'bug'],
+                    description: 'Type of the task.',
+                },
+                parentId: {
+                    type: 'string',
+                    description: 'Optional ID of the parent task.',
+                },
+                dependencies: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional list of task IDs that this task depends on.',
+                },
+            },
+            required: ['title', 'description', 'type'],
+        },
+    },
+};
+export const TRACKER_UPDATE_TASK_DEFINITION = {
+    base: {
+        name: TRACKER_UPDATE_TASK_TOOL_NAME,
+        description: 'Updates an existing task in the tracker.',
+        parametersJsonSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'The 6-character hex ID of the task to update.',
+                },
+                title: {
+                    type: 'string',
+                    description: 'New title for the task.',
+                },
+                description: {
+                    type: 'string',
+                    description: 'New description for the task.',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['open', 'in_progress', 'blocked', 'closed'],
+                    description: 'New status for the task.',
+                },
+                dependencies: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'New list of dependency IDs.',
+                },
+            },
+            required: ['id'],
+        },
+    },
+};
+export const TRACKER_GET_TASK_DEFINITION = {
+    base: {
+        name: TRACKER_GET_TASK_TOOL_NAME,
+        description: 'Retrieves details for a specific task.',
+        parametersJsonSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'The 6-character hex ID of the task.',
+                },
+            },
+            required: ['id'],
+        },
+    },
+};
+export const TRACKER_LIST_TASKS_DEFINITION = {
+    base: {
+        name: TRACKER_LIST_TASKS_TOOL_NAME,
+        description: 'Lists tasks in the tracker, optionally filtered by status, type, or parent.',
+        parametersJsonSchema: {
+            type: 'object',
+            properties: {
+                status: {
+                    type: 'string',
+                    enum: ['open', 'in_progress', 'blocked', 'closed'],
+                    description: 'Filter by status.',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['epic', 'task', 'bug'],
+                    description: 'Filter by type.',
+                },
+                parentId: {
+                    type: 'string',
+                    description: 'Filter by parent task ID.',
+                },
+            },
+        },
+    },
+};
+export const TRACKER_ADD_DEPENDENCY_DEFINITION = {
+    base: {
+        name: TRACKER_ADD_DEPENDENCY_TOOL_NAME,
+        description: 'Adds a dependency between two tasks.',
+        parametersJsonSchema: {
+            type: 'object',
+            properties: {
+                taskId: {
+                    type: 'string',
+                    description: 'The ID of the task that has a dependency.',
+                },
+                dependencyId: {
+                    type: 'string',
+                    description: 'The ID of the task that is being depended upon.',
+                },
+            },
+            required: ['taskId', 'dependencyId'],
+        },
+    },
+};
+export const TRACKER_VISUALIZE_DEFINITION = {
+    base: {
+        name: TRACKER_VISUALIZE_TOOL_NAME,
+        description: 'Renders an ASCII tree visualization of the task graph.',
+        parametersJsonSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+};
+//# sourceMappingURL=trackerTools.js.map

package/dist/src/tools/definitions/trackerTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackerTools.js","sourceRoot":"","sources":["../../../../src/tools/definitions/trackerTools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,6BAA6B,EAC7B,6BAA6B,EAC7B,0BAA0B,EAC1B,4BAA4B,EAC5B,gCAAgC,EAChC,2BAA2B,GAC5B,MAAM,kBAAkB,CAAC;AAE1B,MAAM,CAAC,MAAM,8BAA8B,GAAmB;IAC5D,IAAI,EAAE;QACJ,IAAI,EAAE,6BAA6B;QACnC,WAAW,EAAE,oCAAoC;QACjD,oBAAoB,EAAE;YACpB,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,0BAA0B;iBACxC;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mCAAmC;iBACjD;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC;oBAC7B,WAAW,EAAE,mBAAmB;iBACjC;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,iCAAiC;iBAC/C;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,WAAW,EAAE,sDAAsD;iBACpE;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,EAAE,aAAa,EAAE,MAAM,CAAC;SAC3C;KACF;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,8BAA8B,GAAmB;IAC5D,IAAI,EAAE;QACJ,IAAI,EAAE,6BAA6B;QACnC,WAAW,EAAE,0CAA0C;QACvD,oBAAoB,EAAE;YACpB,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,EAAE,EAAE;oBACF,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+CAA+C;iBAC7D;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,yBAAyB;iBACvC;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+BAA+B;iBAC7C;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,CAAC;oBAClD,WAAW,EAAE,0BAA0B;iBACxC;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,WAAW,EAAE,6BAA6B;iBAC3C;aACF;YACD,QAAQ,EAAE,CAAC,IAAI,CAAC;SACjB;KACF;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAmB;IACzD,IAAI,EAAE;QACJ,IAAI,EAAE,0BAA0B;QAChC,WAAW,EAAE,wCAAwC;QACrD,oBAAoB,EAAE;YACpB,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,EAAE,EAAE;oBACF,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,qCAAqC;iBACnD;aACF;YACD,QAAQ,EAAE,CAAC,IAAI,CAAC;SACjB;KACF;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,6BAA6B,GAAmB;IAC3D,IAAI,EAAE;QACJ,IAAI,EAAE,4BAA4B;QAClC,WAAW,EACT,6EAA6E;QAC/E,oBAAoB,EAAE;YACpB,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,CAAC;oBAClD,WAAW,EAAE,mBAAmB;iBACjC;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC;oBAC7B,WAAW,EAAE,iBAAiB;iBAC/B;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2BAA2B;iBACzC;aACF;SACF;KACF;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,iCAAiC,GAAmB;IAC/D,IAAI,EAAE;QACJ,IAAI,EAAE,gCAAgC;QACtC,WAAW,EAAE,sCAAsC;QACnD,oBAAoB,EAAE;YACpB,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2CAA2C;iBACzD;gBACD,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,iDAAiD;iBAC/D;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC;SACrC;KACF;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,4BAA4B,GAAmB;IAC1D,IAAI,EAAE;QACJ,IAAI,EAAE,2BAA2B;QACjC,WAAW,EAAE,wDAAwD;QACrE,oBAAoB,EAAE;YACpB,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE;SACf;KACF;CACF,CAAC"}

package/dist/src/tools/diff-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Generates a snippet of the diff between two strings, including a few lines of context around the changes.
+ */
+export declare function getDiffContextSnippet(originalContent: string, newContent: string, contextLines?: number): string;

package/dist/src/tools/diff-utils.js

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as Diff from 'diff';
+/**
+ * Generates a snippet of the diff between two strings, including a few lines of context around the changes.
+ */
+export function getDiffContextSnippet(originalContent, newContent, contextLines = 5) {
+    if (!originalContent) {
+        return newContent;
+    }
+    const changes = Diff.diffLines(originalContent, newContent);
+    const newLines = newContent.split(/\r?\n/);
+    const ranges = [];
+    let newLineIdx = 0;
+    for (const change of changes) {
+        if (change.added) {
+            ranges.push({ start: newLineIdx, end: newLineIdx + (change.count ?? 0) });
+            newLineIdx += change.count ?? 0;
+        }
+        else if (change.removed) {
+            ranges.push({ start: newLineIdx, end: newLineIdx });
+        }
+        else {
+            newLineIdx += change.count ?? 0;
+        }
+    }
+    if (ranges.length === 0) {
+        return newContent;
+    }
+    const expandedRanges = ranges.map((r) => ({
+        start: Math.max(0, r.start - contextLines),
+        end: Math.min(newLines.length, r.end + contextLines),
+    }));
+    expandedRanges.sort((a, b) => a.start - b.start);
+    const mergedRanges = [];
+    if (expandedRanges.length > 0) {
+        let current = expandedRanges[0];
+        for (let i = 1; i < expandedRanges.length; i++) {
+            const next = expandedRanges[i];
+            if (next.start <= current.end) {
+                current.end = Math.max(current.end, next.end);
+            }
+            else {
+                mergedRanges.push(current);
+                current = next;
+            }
+        }
+        mergedRanges.push(current);
+    }
+    const outputParts = [];
+    let lastEnd = 0;
+    for (const range of mergedRanges) {
+        if (range.start > lastEnd)
+            outputParts.push('...');
+        outputParts.push(newLines.slice(range.start, range.end).join('\n'));
+        lastEnd = range.end;
+    }
+    if (lastEnd < newLines.length) {
+        outputParts.push('...');
+    }
+    return outputParts.join('\n');
+}
+//# sourceMappingURL=diff-utils.js.map

package/dist/src/tools/diff-utils.js.map

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

package/dist/src/tools/diff-utils.test.d.ts

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

package/dist/src/tools/diff-utils.test.js

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, expect, it } from 'vitest';
+import { getDiffContextSnippet } from './diff-utils.js';
+describe('getDiffContextSnippet', () => {
+    it('should return the whole new content if originalContent is empty', () => {
+        const original = '';
+        const modified = 'line1\nline2\nline3';
+        expect(getDiffContextSnippet(original, modified)).toBe(modified);
+    });
+    it('should return the whole content if there are no changes', () => {
+        const content = 'line1\nline2\nline3';
+        expect(getDiffContextSnippet(content, content)).toBe(content);
+    });
+    it('should show added lines with context', () => {
+        const original = '1\n2\n3\n4\n5\n6\n7\n8\n9\n10';
+        const modified = '1\n2\n3\n4\n5\nadded\n6\n7\n8\n9\n10';
+        // Default context is 5 lines.
+        expect(getDiffContextSnippet(original, modified)).toBe(modified);
+    });
+    it('should use ellipses for changes far apart', () => {
+        const original = Array.from({ length: 20 }, (_, i) => `${i + 1}`).join('\n');
+        const modified = original
+            .replace('2\n', '2\nadded1\n')
+            .replace('19', '19\nadded2');
+        const snippet = getDiffContextSnippet(original, modified, 2);
+        expect(snippet).toContain('1\n2\nadded1\n3\n4');
+        expect(snippet).toContain('...');
+        expect(snippet).toContain('18\n19\nadded2\n20');
+    });
+    it('should respect custom contextLines', () => {
+        const original = '1\n2\n3\n4\n5\n6\n7\n8\n9\n10';
+        const modified = '1\n2\n3\n4\n5\nadded\n6\n7\n8\n9\n10';
+        const snippet = getDiffContextSnippet(original, modified, 1);
+        expect(snippet).toBe('...\n5\nadded\n6\n...');
+    });
+    it('should handle multiple changes close together by merging ranges', () => {
+        const original = '1\n2\n3\n4\n5\n6\n7\n8\n9\n10';
+        const modified = '1\nadded1\n2\nadded2\n3\n4\n5\n6\n7\n8\n9\n10';
+        const snippet = getDiffContextSnippet(original, modified, 1);
+        expect(snippet).toBe('1\nadded1\n2\nadded2\n3\n...');
+    });
+    it('should handle removals', () => {
+        const original = '1\n2\n3\n4\n5\n6\n7\n8\n9\n10';
+        const modified = '1\n2\n3\n4\n6\n7\n8\n9\n10';
+        const snippet = getDiffContextSnippet(original, modified, 1);
+        expect(snippet).toBe('...\n4\n6\n...');
+    });
+});
+//# sourceMappingURL=diff-utils.test.js.map

package/dist/src/tools/diff-utils.test.js.map

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

package/dist/src/tools/grep-utils.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Result object for a single grep match
+ */
+export interface GrepMatch {
+    filePath: string;
+    absolutePath: string;
+    lineNumber: number;
+    line: string;
+    isContext?: boolean;
+}
+/**
+ * Groups matches by their file path and ensures they are sorted by line number.
+ */
+export declare function groupMatchesByFile(allMatches: GrepMatch[]): Record<string, GrepMatch[]>;
+/**
+ * Reads the content of a file and splits it into lines.
+ * Returns null if the file cannot be read.
+ */
+export declare function readFileLines(absolutePath: string): Promise<string[] | null>;
+/**
+ * Automatically enriches grep results with surrounding context if the match count is low
+ * and no specific context was requested. This optimization can enable the agent
+ * to skip turns that would be spent reading files after grep calls.
+ */
+export declare function enrichWithAutoContext(matchesByFile: Record<string, GrepMatch[]>, matchCount: number, params: {
+    names_only?: boolean;
+    context?: number;
+    before?: number;
+    after?: number;
+}): Promise<void>;
+/**
+ * Formats the grep results for the LLM, including optional context.
+ */
+export declare function formatGrepResults(allMatches: GrepMatch[], params: {
+    pattern: string;
+    names_only?: boolean;
+    include_pattern?: string;
+    context?: number;
+    before?: number;
+    after?: number;
+}, searchLocationDescription: string, totalMaxMatches: number): Promise<{
+    llmContent: string;
+    returnDisplay: string;
+}>;

package/dist/src/tools/grep-utils.js

@@ -0,0 +1,147 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fsPromises from 'node:fs/promises';
+import { debugLogger } from '../utils/debugLogger.js';
+import { MAX_LINE_LENGTH_TEXT_FILE } from '../utils/constants.js';
+/**
+ * Groups matches by their file path and ensures they are sorted by line number.
+ */
+export function groupMatchesByFile(allMatches) {
+    const groups = {};
+    for (const match of allMatches) {
+        if (!groups[match.filePath]) {
+            groups[match.filePath] = [];
+        }
+        groups[match.filePath].push(match);
+    }
+    for (const filePath in groups) {
+        groups[filePath].sort((a, b) => a.lineNumber - b.lineNumber);
+    }
+    return groups;
+}
+/**
+ * Reads the content of a file and splits it into lines.
+ * Returns null if the file cannot be read.
+ */
+export async function readFileLines(absolutePath) {
+    try {
+        const content = await fsPromises.readFile(absolutePath, 'utf8');
+        return content.split(/\r?\n/);
+    }
+    catch (err) {
+        debugLogger.warn(`Failed to read file for context: ${absolutePath}`, err);
+        return null;
+    }
+}
+/**
+ * Automatically enriches grep results with surrounding context if the match count is low
+ * and no specific context was requested. This optimization can enable the agent
+ * to skip turns that would be spent reading files after grep calls.
+ */
+export async function enrichWithAutoContext(matchesByFile, matchCount, params) {
+    const { names_only, context, before, after } = params;
+    if (matchCount >= 1 &&
+        matchCount <= 3 &&
+        !names_only &&
+        context === undefined &&
+        before === undefined &&
+        after === undefined) {
+        const contextLines = matchCount === 1 ? 50 : 15;
+        for (const filePath in matchesByFile) {
+            const fileMatches = matchesByFile[filePath];
+            if (fileMatches.length === 0)
+                continue;
+            const fileLines = await readFileLines(fileMatches[0].absolutePath);
+            if (fileLines) {
+                const newFileMatches = [];
+                const seenLines = new Set();
+                // Sort matches to process them in order
+                fileMatches.sort((a, b) => a.lineNumber - b.lineNumber);
+                for (const match of fileMatches) {
+                    const startLine = Math.max(0, match.lineNumber - 1 - contextLines);
+                    const endLine = Math.min(fileLines.length, match.lineNumber - 1 + contextLines + 1);
+                    for (let i = startLine; i < endLine; i++) {
+                        const lineNum = i + 1;
+                        if (!seenLines.has(lineNum)) {
+                            newFileMatches.push({
+                                absolutePath: match.absolutePath,
+                                filePath: match.filePath,
+                                lineNumber: lineNum,
+                                line: fileLines[i],
+                                isContext: lineNum !== match.lineNumber,
+                            });
+                            seenLines.add(lineNum);
+                        }
+                        else if (lineNum === match.lineNumber) {
+                            const existing = newFileMatches.find((m) => m.lineNumber === lineNum);
+                            if (existing) {
+                                existing.isContext = false;
+                            }
+                        }
+                    }
+                }
+                matchesByFile[filePath] = newFileMatches.sort((a, b) => a.lineNumber - b.lineNumber);
+            }
+        }
+    }
+}
+/**
+ * Formats the grep results for the LLM, including optional context.
+ */
+export async function formatGrepResults(allMatches, params, searchLocationDescription, totalMaxMatches) {
+    const { pattern, names_only, include_pattern } = params;
+    if (allMatches.length === 0) {
+        const noMatchMsg = `No matches found for pattern "${pattern}" ${searchLocationDescription}${include_pattern ? ` (filter: "${include_pattern}")` : ''}.`;
+        return { llmContent: noMatchMsg, returnDisplay: `No matches found` };
+    }
+    const matchesByFile = groupMatchesByFile(allMatches);
+    const matchesOnly = allMatches.filter((m) => !m.isContext);
+    const matchCount = matchesOnly.length; // Count actual matches, not context lines
+    const matchTerm = matchCount === 1 ? 'match' : 'matches';
+    // If the result count is low and Gemini didn't request before/after lines of context
+    // add a small amount anyways to enable the agent to avoid one or more extra turns
+    // reading the matched files. This optimization reduces turns count by ~10% in SWEBench.
+    await enrichWithAutoContext(matchesByFile, matchCount, params);
+    const wasTruncated = matchCount >= totalMaxMatches;
+    if (names_only) {
+        const filePaths = Object.keys(matchesByFile).sort();
+        let llmContent = `Found ${filePaths.length} files with matches for pattern "${pattern}" ${searchLocationDescription}${include_pattern ? ` (filter: "${include_pattern}")` : ''}${wasTruncated
+            ? ` (results limited to ${totalMaxMatches} matches for performance)`
+            : ''}:\n`;
+        llmContent += filePaths.join('\n');
+        return {
+            llmContent: llmContent.trim(),
+            returnDisplay: `Found ${filePaths.length} files${wasTruncated ? ' (limited)' : ''}`,
+        };
+    }
+    let llmContent = `Found ${matchCount} ${matchTerm} for pattern "${pattern}" ${searchLocationDescription}${include_pattern ? ` (filter: "${include_pattern}")` : ''}`;
+    if (wasTruncated) {
+        llmContent += ` (results limited to ${totalMaxMatches} matches for performance)`;
+    }
+    llmContent += `:\n---\n`;
+    for (const filePath in matchesByFile) {
+        llmContent += `File: ${filePath}\n`;
+        matchesByFile[filePath].forEach((match) => {
+            // If isContext is undefined, assume it's a match (false)
+            const separator = match.isContext ? '-' : ':';
+            // trimEnd to avoid double newlines if line has them, but we want to preserve indentation
+            let lineContent = match.line.trimEnd();
+            const graphemes = Array.from(lineContent);
+            if (graphemes.length > MAX_LINE_LENGTH_TEXT_FILE) {
+                lineContent =
+                    graphemes.slice(0, MAX_LINE_LENGTH_TEXT_FILE).join('') +
+                        '... [truncated]';
+            }
+            llmContent += `L${match.lineNumber}${separator} ${lineContent}\n`;
+        });
+        llmContent += '---\n';
+    }
+    return {
+        llmContent: llmContent.trim(),
+        returnDisplay: `Found ${matchCount} ${matchTerm}${wasTruncated ? ' (limited)' : ''}`,
+    };
+}
+//# sourceMappingURL=grep-utils.js.map

package/dist/src/tools/grep-utils.js.map

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