@cleanslate/sdk 0.1.0

package/dist/tools/ReadFileRangeTool.js

@@ -0,0 +1,150 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) CleanSlate. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+import { CLEANSLATE_MAX_FILE_READ_LINES, resolveCleanSlateFileReadBudget, takeCleanSlateBoundedLineSlice } from './cleanSlateFileReadPolicy.js';
+import { resolvePathToUri } from './utils.js';
+/**
+ * Tool: read_file_range
+ */
+export const readFileRangeTool = {
+    name: 'read_file_range',
+    description: 'Reads a complete bounded line range from a file. Input: { path: string, startLine: number, endLine: number } (aliases start_line/end_line also supported). Returns the exact returned range, totalLines, and nextStartLine when more content remains; it never silently truncates content.',
+    parametersSchema: {
+        path: "string",
+        startLine: "number",
+        endLine: "number",
+        start_line: "number",
+        end_line: "number"
+    },
+    category: "discovery",
+    planningHint: "Use the explicit range suggested by a file_too_large read_file result, or a targeted range found through search. Read only non-overlapping ranges that are actually needed.",
+    async run(input, context) {
+        const path = input.path;
+        const startLine = typeof input.startLine === 'number' ? input.startLine : input.start_line;
+        const endLine = typeof input.endLine === 'number' ? input.endLine : input.end_line;
+        if (!path)
+            throw new Error('read_file_range requires a "path" parameter');
+        if (typeof startLine !== 'number' || typeof endLine !== 'number') {
+            throw new Error('read_file_range requires "startLine"/"endLine" (or "start_line"/"end_line") parameters as numbers');
+        }
+        if (!Number.isFinite(startLine) || !Number.isFinite(endLine)) {
+            throw new Error('read_file_range requires finite numeric startLine/endLine');
+        }
+        const normalizedStart = Math.max(1, Math.floor(startLine));
+        const normalizedEnd = Math.max(normalizedStart, Math.floor(endLine));
+        const requestedLineCount = normalizedEnd - normalizedStart + 1;
+        const cappedEnd = normalizedStart + Math.min(requestedLineCount, CLEANSLATE_MAX_FILE_READ_LINES) - 1;
+        try {
+            const uri = resolvePathToUri(path, context);
+            context.onProgress?.({ type: 'read', path: uri.fsPath });
+            let content = '';
+            let currentVersionId;
+            let mtime;
+            const model = context.modelService.getModel(uri);
+            if (model) {
+                content = model.getValue();
+                currentVersionId = model.getVersionId();
+            }
+            else {
+                const fileContent = await context.textFileService.read(uri);
+                content = fileContent.value;
+            }
+            try {
+                mtime = (await context.fileService.stat(uri)).mtime;
+            }
+            catch {
+                // Some schemes do not expose file metadata; version guards still apply when a model exists.
+            }
+            const lines = content.split('\n');
+            const config = context.configService.getConfiguration();
+            const contextWindowTokens = context.fileReadBudget?.contextWindowTokens
+                ?? config.contextWindow
+                ?? config.maxInputTokens
+                ?? 64_000;
+            const availableInputTokens = context.fileReadBudget?.availableInputTokens ?? contextWindowTokens;
+            const readBudget = resolveCleanSlateFileReadBudget(contextWindowTokens, availableInputTokens);
+            const startIdx = normalizedStart - 1;
+            const endIdxExclusive = Math.min(lines.length, cappedEnd);
+            if (startIdx >= lines.length) {
+                throw new Error(`Start line ${normalizedStart} is beyond the end of the file (${lines.length} lines)`);
+            }
+            const boundedSlice = takeCleanSlateBoundedLineSlice(lines, startIdx, endIdxExclusive, readBudget.maxBytes);
+            if (boundedSlice.oversizedFirstLine) {
+                return {
+                    success: false,
+                    code: 'line_too_large',
+                    path: uri.fsPath,
+                    totalLines: lines.length,
+                    maxBytes: readBudget.maxBytes,
+                    maxTokens: readBudget.maxTokens,
+                    message: `Line ${normalizedStart} exceeds this model turn's file-read budget of ${readBudget.maxBytes} UTF-8 bytes / ${readBudget.maxTokens} estimated tokens. No partial line was returned.`,
+                    recoveryHint: 'Use grep_search or another targeted structured tool instead of reading this generated/minified line as source text.'
+                };
+            }
+            const rangeContent = boundedSlice.content;
+            const actualEndLine = Math.max(normalizedStart, boundedSlice.endExclusive);
+            const requestedEndWithinFile = Math.min(lines.length, normalizedEnd);
+            const truncated = boundedSlice.endExclusive < requestedEndWithinFile || normalizedEnd > cappedEnd;
+            const hasMore = actualEndLine < lines.length;
+            const previousReadState = context.readFileState?.get(uri.toString());
+            const canReusePreviousRanges = previousReadState
+                && previousReadState.currentVersionId === currentVersionId
+                && previousReadState.mtime === mtime;
+            const previousRanges = canReusePreviousRanges ? previousReadState.ranges ?? [] : [];
+            const nextRange = {
+                startLine: normalizedStart,
+                endLine: actualEndLine,
+                content: rangeContent,
+                currentVersionId,
+                mtime,
+                readAt: Date.now()
+            };
+            const ranges = [
+                ...previousRanges.filter(range => range.startLine !== nextRange.startLine || range.endLine !== nextRange.endLine),
+                nextRange
+            ].slice(-32);
+            context.readFileState?.set(uri.toString(), {
+                path: uri.fsPath,
+                uri: uri.toString(),
+                content: rangeContent,
+                currentVersionId,
+                mtime,
+                totalLines: lines.length,
+                isPartialView: true,
+                readAt: nextRange.readAt,
+                ranges
+            });
+            return {
+                content: rangeContent,
+                path: uri.fsPath,
+                range: { startLine: normalizedStart, endLine: actualEndLine },
+                totalLines: lines.length,
+                currentVersionId,
+                truncated,
+                hasMore,
+                nextStartLine: hasMore ? actualEndLine + 1 : undefined,
+                maxBytes: readBudget.maxBytes,
+                maxTokens: readBudget.maxTokens
+            };
+        }
+        catch (error) {
+            const message = String(error);
+            const isMissingFile = message.includes('Unable to resolve nonexistent file')
+                || message.includes('not found')
+                || message.includes('does not exist');
+            return {
+                success: false,
+                code: isMissingFile ? 'not_found' : 'read_failed',
+                path,
+                message: isMissingFile
+                    ? `File not found: "${path}". Discover the real file path before requesting a range read.`
+                    : `Failed to read file range "${path}": ${message}`,
+                recoveryHint: isMissingFile
+                    ? 'Use list_dir(".") or find_by_name to locate the file first, then retry the range read.'
+                    : 'Verify the path and line range, then retry.'
+            };
+        }
+    }
+};
+//# sourceMappingURL=ReadFileRangeTool.js.map

package/dist/tools/ReadFileRangeTool.js.map

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

package/dist/tools/ReadFileTool.d.ts

@@ -0,0 +1,6 @@
+import { CleanSlateTool } from './types.js';
+/**
+ * Tool: read_file
+ */
+export declare const readFileTool: CleanSlateTool;
+//# sourceMappingURL=ReadFileTool.d.ts.map

package/dist/tools/ReadFileTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadFileTool.d.ts","sourceRoot":"","sources":["../../src/tools/ReadFileTool.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAyB,MAAM,YAAY,CAAC;AAKnE;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,cAiL1B,CAAC"}

package/dist/tools/ReadFileTool.js

@@ -0,0 +1,183 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) CleanSlate. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+import { CLEANSLATE_ARTIFACT_SCHEME } from '../protocol/cleanSlateAI.js';
+import { getVirtualArtifactType, resolvePathToUri } from './utils.js';
+import { isStaleGeneratedDiagnosticPath, STALE_GENERATED_DIAGNOSTIC_WARNING } from './cleanSlateStaleDiagnosticPolicy.js';
+import { CLEANSLATE_MAX_FILE_READ_LINES, CLEANSLATE_MAX_FULL_FILE_READ_BYTES, estimateCleanSlateFileReadTokens, estimateCleanSlateUtf8Bytes, resolveCleanSlateFileReadBudget, takeCleanSlateBoundedLineSlice } from './cleanSlateFileReadPolicy.js';
+/**
+ * Tool: read_file
+ */
+export const readFileTool = {
+    name: 'read_file',
+    description: 'Reads a complete text file from the workspace when it fits the file-read budget. Input: { path: string }. Large files return a structured file_too_large result with available size/line metadata and a suggested read_file_range; content is never silently truncated.',
+    parametersSchema: {
+        path: "string"
+    },
+    category: "discovery",
+    planningHint: "Use when complete file content is required. If the tool reports file_too_large, use its suggested read_file_range instead of repeating the same read or running wc.",
+    async run(input, context) {
+        const { path } = input;
+        if (!path)
+            throw new Error('read_file requires a "path" parameter');
+        try {
+            const uri = resolvePathToUri(path, context);
+            context.onProgress?.({ type: 'read', path: uri.fsPath });
+            let content = '';
+            let languageId = 'plaintext';
+            let currentVersionId;
+            let mtime;
+            // Check if it's a virtual artifact FIRST
+            if (uri.scheme === CLEANSLATE_ARTIFACT_SCHEME) {
+                const artifactType = getVirtualArtifactType(path);
+                let artifact;
+                if (artifactType === 'implementation_plan')
+                    artifact = context.artifactService.getLatestArtifactByType('implementation_plan', { sessionId: context.sessionId });
+                else if (artifactType === 'walkthrough')
+                    artifact = context.artifactService.getLatestArtifactByType('walkthrough', { sessionId: context.sessionId });
+                else if (artifactType === 'analysis')
+                    artifact = context.artifactService.getLatestArtifactByType('analysis', { sessionId: context.sessionId });
+                if (artifact) {
+                    content = artifact.content;
+                    languageId = 'markdown';
+                    return { content, languageId, path: uri.toString() };
+                }
+                throw new Error(`Virtual artifact "${path}" not found.`);
+            }
+            const config = context.configService.getConfiguration();
+            const contextWindowTokens = context.fileReadBudget?.contextWindowTokens
+                ?? config.contextWindow
+                ?? config.maxInputTokens
+                ?? 64_000;
+            const availableInputTokens = context.fileReadBudget?.availableInputTokens ?? contextWindowTokens;
+            const readBudget = resolveCleanSlateFileReadBudget(contextWindowTokens, availableInputTokens);
+            const model = context.modelService.getModel(uri);
+            let fileSize;
+            try {
+                const stat = await context.fileService.stat(uri);
+                mtime = stat.mtime;
+                fileSize = stat.size;
+            }
+            catch {
+                // Some schemes do not expose file metadata; the adaptive result budget still applies.
+            }
+            if (!model && typeof fileSize === 'number' && fileSize > CLEANSLATE_MAX_FULL_FILE_READ_BYTES) {
+                context.readFileState?.set(uri.toString(), {
+                    path: uri.fsPath,
+                    uri: uri.toString(),
+                    currentVersionId,
+                    mtime,
+                    isPartialView: true,
+                    readAt: Date.now(),
+                    ranges: []
+                });
+                return {
+                    success: false,
+                    code: 'file_too_large',
+                    path: uri.fsPath,
+                    totalBytes: fileSize,
+                    maxFullFileBytes: CLEANSLATE_MAX_FULL_FILE_READ_BYTES,
+                    maxBytes: readBudget.maxBytes,
+                    maxTokens: readBudget.maxTokens,
+                    contextWindowTokens: readBudget.contextWindowTokens,
+                    availableInputTokens: readBudget.availableInputTokens,
+                    suggestedRange: { startLine: 1, endLine: CLEANSLATE_MAX_FILE_READ_LINES },
+                    message: `File is ${fileSize} bytes, exceeding the ${CLEANSLATE_MAX_FULL_FILE_READ_BYTES}-byte unrestricted full-read safety limit. The file was not loaded and no partial content was returned.`,
+                    recoveryHint: 'Use a targeted search or read_file_range with the suggested starting range. Continue with later non-overlapping ranges only when needed.'
+                };
+            }
+            if (model) {
+                content = model.getValue();
+                languageId = model.getLanguageId();
+                currentVersionId = model.getVersionId();
+            }
+            else {
+                const fileContent = await context.textFileService.read(uri);
+                content = fileContent.value;
+                // `read` reports a text encoding, not a language. With no model
+                // resolved there is nothing to ask, so leave the default rather
+                // than reporting "utf8" as the file's language.
+                languageId = 'plaintext';
+            }
+            const totalLines = content.split('\n').length;
+            const totalBytes = estimateCleanSlateUtf8Bytes(content);
+            const estimatedTokens = estimateCleanSlateFileReadTokens(content);
+            if (totalBytes > readBudget.maxBytes || estimatedTokens > readBudget.maxTokens) {
+                const lines = content.split('\n');
+                const suggestedSlice = takeCleanSlateBoundedLineSlice(lines, 0, Math.min(totalLines, CLEANSLATE_MAX_FILE_READ_LINES), readBudget.maxBytes);
+                const suggestedEndLine = Math.max(1, suggestedSlice.endExclusive);
+                context.readFileState?.set(uri.toString(), {
+                    path: uri.fsPath,
+                    uri: uri.toString(),
+                    totalLines,
+                    currentVersionId,
+                    mtime,
+                    isPartialView: true,
+                    readAt: Date.now(),
+                    ranges: []
+                });
+                return {
+                    success: false,
+                    code: 'file_too_large',
+                    path: uri.fsPath,
+                    totalLines,
+                    totalBytes,
+                    estimatedTokens,
+                    maxBytes: readBudget.maxBytes,
+                    maxTokens: readBudget.maxTokens,
+                    contextWindowTokens: readBudget.contextWindowTokens,
+                    availableInputTokens: readBudget.availableInputTokens,
+                    currentVersionId,
+                    suggestedRange: {
+                        startLine: 1,
+                        endLine: suggestedEndLine
+                    },
+                    message: `File has ${totalLines} lines, ${totalBytes} UTF-8 bytes, and approximately ${estimatedTokens} tokens. It exceeds this model turn's complete-read budget of ${readBudget.maxBytes} bytes / ${readBudget.maxTokens} estimated tokens. No partial content was returned.`,
+                    recoveryHint: 'Call read_file_range once with the suggested range, then continue with later non-overlapping ranges only when those sections are needed. Do not repeat read_file or run wc; totalLines is already provided.'
+                };
+            }
+            context.readFileState?.set(uri.toString(), {
+                path: uri.fsPath,
+                uri: uri.toString(),
+                content,
+                totalLines,
+                currentVersionId,
+                mtime,
+                isPartialView: false,
+                readAt: Date.now(),
+                ranges: []
+            });
+            if (isStaleGeneratedDiagnosticPath(path) || isStaleGeneratedDiagnosticPath(uri.fsPath)) {
+                return {
+                    content,
+                    languageId,
+                    path: uri.fsPath,
+                    totalLines,
+                    currentVersionId,
+                    staleGeneratedDiagnostic: true,
+                    warning: STALE_GENERATED_DIAGNOSTIC_WARNING
+                };
+            }
+            return { content, languageId, path: uri.fsPath, totalLines, currentVersionId, truncated: false };
+        }
+        catch (error) {
+            const message = String(error);
+            const isMissingFile = message.includes('Unable to resolve nonexistent file')
+                || message.includes('not found')
+                || message.includes('does not exist');
+            return {
+                success: false,
+                code: isMissingFile ? 'not_found' : 'read_failed',
+                path,
+                message: isMissingFile
+                    ? `File not found: "${path}". Do not assume common manifest files exist. Inspect the actual root listing and only read files that were discovered in this workspace.`
+                    : `Failed to read file "${path}": ${message}`,
+                recoveryHint: isMissingFile
+                    ? 'Use list_dir(".") or find_by_name first, then read only files that actually exist.'
+                    : 'Verify the path and retry. If the file is large, consider read_file_range after locating the correct target.'
+            };
+        }
+    }
+};
+//# sourceMappingURL=ReadFileTool.js.map

package/dist/tools/ReadFileTool.js.map

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

package/dist/tools/ReadLintsTool.d.ts

@@ -0,0 +1,6 @@
+import { CleanSlateTool } from './types.js';
+/**
+ * Tool: read_lints
+ */
+export declare const readLintsTool: CleanSlateTool;
+//# sourceMappingURL=ReadLintsTool.d.ts.map

package/dist/tools/ReadLintsTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadLintsTool.d.ts","sourceRoot":"","sources":["../../src/tools/ReadLintsTool.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAyB,MAAM,YAAY,CAAC;AAGnE;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,cA8E3B,CAAC"}

package/dist/tools/ReadLintsTool.js

@@ -0,0 +1,83 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) CleanSlate. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+import { MarkerSeverity } from '../host/diagnostics.js';
+import { resolvePathToUri } from './utils.js';
+/**
+ * Tool: read_lints
+ */
+export const readLintsTool = {
+    name: 'read_lints',
+    description: 'Reads diagnostics (errors, warnings, hints) from the VS Code marker service. Input: { path?: string, paths?: string[] }. If path or paths are provided, returns lints for those files. If omitted, returns lints for the whole workspace.',
+    parametersSchema: {
+        path: "string (optional)",
+        paths: "string[] (optional) - Preferred after multi-file edits; scopes diagnostics to these files."
+    },
+    category: "discovery",
+    planningHint: "Use after edits to verify there are no new syntax or compiler errors.",
+    async run(input, context) {
+        const requestedPaths = [
+            ...(typeof input.path === 'string' && input.path.trim().length > 0 ? [input.path] : []),
+            ...(Array.isArray(input.paths) ? input.paths.filter((path) => typeof path === 'string' && path.trim().length > 0) : [])
+        ];
+        const uniquePaths = [...new Set(requestedPaths)];
+        const resources = [];
+        for (const path of uniquePaths) {
+            try {
+                resources.push(resolvePathToUri(path, context));
+            }
+            catch (error) {
+                return { success: false, message: `Invalid path: ${path}` };
+            }
+        }
+        const markers = resources.length > 0
+            ? resources.flatMap(resource => context.markerService.read({ resource }))
+            : context.markerService.read({});
+        // Filter to errors and warnings only, or include all?
+        // Let's include everything but label them.
+        const results = markers.map(marker => {
+            // Broadcast focus lines for each significant diagnostic
+            if (context.recentFocusLines && marker.resource) {
+                const uriStr = marker.resource.toString();
+                if (!context.recentFocusLines.has(uriStr)) {
+                    context.recentFocusLines.set(uriStr, new Set());
+                }
+                const focusSet = context.recentFocusLines.get(uriStr);
+                for (let i = marker.startLineNumber; i <= marker.endLineNumber; i++) {
+                    focusSet.add(i);
+                }
+            }
+            return {
+                severity: MarkerSeverity.toString(marker.severity),
+                message: marker.message,
+                startLineNumber: marker.startLineNumber,
+                startColumn: marker.startColumn,
+                endLineNumber: marker.endLineNumber,
+                endColumn: marker.endColumn,
+                source: marker.source,
+                code: marker.code,
+                resource: marker.resource?.fsPath ?? marker.resource?.toString()
+            };
+        });
+        if (results.length === 0) {
+            const target = uniquePaths.length === 1
+                ? uniquePaths[0]
+                : uniquePaths.length > 1
+                    ? `${uniquePaths.length} files`
+                    : 'workspace';
+            return {
+                success: true,
+                message: `No lints found in ${target}.`,
+                errors: []
+            };
+        }
+        // Group by resource for easier reading if it's a workspace search
+        return {
+            success: true,
+            scopedPaths: uniquePaths,
+            errors: results
+        };
+    }
+};
+//# sourceMappingURL=ReadLintsTool.js.map

package/dist/tools/ReadLintsTool.js.map

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

package/dist/tools/ReadReferenceTool.d.ts

@@ -0,0 +1,6 @@
+import { CleanSlateTool } from './types.js';
+/**
+ * Tool: read_reference
+ */
+export declare const readReferenceTool: CleanSlateTool;
+//# sourceMappingURL=ReadReferenceTool.d.ts.map

package/dist/tools/ReadReferenceTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadReferenceTool.d.ts","sourceRoot":"","sources":["../../src/tools/ReadReferenceTool.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAyB,MAAM,YAAY,CAAC;AAEnE;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAe/B,CAAC"}

package/dist/tools/ReadReferenceTool.js

@@ -0,0 +1,24 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) CleanSlate. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+/**
+ * Tool: read_reference
+ */
+export const readReferenceTool = {
+    name: 'read_reference',
+    description: 'Retrieves the full content of a "sniped" tool result using its Reference ID. Input: { referenceId: string }. Returns: { content: string }',
+    parametersSchema: {
+        referenceId: "string - The Unique ID provided in the previous tool output placeholder (e.g. REF-123)"
+    },
+    category: "system",
+    async run(input, _context) {
+        // The implementation is handled in CleanSlateAgent by looking up its internal referenceBuffer
+        return {
+            success: true,
+            isReferenceRequest: true,
+            referenceId: input.referenceId
+        };
+    }
+};
+//# sourceMappingURL=ReadReferenceTool.js.map

package/dist/tools/ReadReferenceTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadReferenceTool.js","sourceRoot":"","sources":["../../src/tools/ReadReferenceTool.ts"],"names":[],"mappings":"AAAA;;;gGAGgG;AAIhG;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAmB;IAC7C,IAAI,EAAE,gBAAgB;IACtB,WAAW,EAAE,2IAA2I;IACxJ,gBAAgB,EAAE;QACd,WAAW,EAAE,wFAAwF;KACxG;IACD,QAAQ,EAAE,QAAQ;IAClB,KAAK,CAAC,GAAG,CAAC,KAA8B,EAAE,QAA+B;QACrE,8FAA8F;QAC9F,OAAO;YACH,OAAO,EAAE,IAAI;YACb,kBAAkB,EAAE,IAAI;YACxB,WAAW,EAAE,KAAK,CAAC,WAAW;SACjC,CAAC;IACN,CAAC;CACJ,CAAC"}

package/dist/tools/ReadSymbolsTool.d.ts

@@ -0,0 +1,3 @@
+import { CleanSlateTool } from './types.js';
+export declare const readSymbolsTool: CleanSlateTool;
+//# sourceMappingURL=ReadSymbolsTool.d.ts.map

package/dist/tools/ReadSymbolsTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReadSymbolsTool.d.ts","sourceRoot":"","sources":["../../src/tools/ReadSymbolsTool.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAyB,MAAM,YAAY,CAAC;AAMnE,eAAO,MAAM,eAAe,EAAE,cAgF7B,CAAC"}

package/dist/tools/ReadSymbolsTool.js

@@ -0,0 +1,100 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) CleanSlate. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+import { resolvePathToUri } from './utils.js';
+import { buildSymbolContext, symbolKindToLabel } from './symbolContext.js';
+import { fireDocumentSymbolProvider, resolveBackgroundLanguageFeatureModel } from './languageFeatureActivation.js';
+import { cancellationTokenFromAbortSignal } from '../services/cleanSlateCancellation.js';
+export const readSymbolsTool = {
+    name: 'read_symbols',
+    description: 'Fetch all symbols plus a semantic owner map for each line using LSP. Use this to distinguish duplicate method/class names and target edits by symbolPath.',
+    parametersSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Path to the file relative to the workspace root.' }
+        },
+        required: ['path']
+    },
+    async run(input, context) {
+        if (!input.path || typeof input.path !== 'string') {
+            return {
+                success: false,
+                code: 'invalid_input',
+                message: 'The "path" argument is required and must be a non-empty string.',
+                recoveryHint: 'Specify the relative path to the file you want to read symbols from.'
+            };
+        }
+        if (!context.languageFeaturesService && !context.commandService) {
+            return { success: false, message: 'Language features command and provider services are not available.' };
+        }
+        const uri = resolvePathToUri(input.path, context);
+        const firedSymbols = await fireDocumentSymbolProvider(uri, context);
+        const model = await resolveBackgroundLanguageFeatureModel(uri, context);
+        if (!model) {
+            const fileContent = await context.textFileService.read(uri);
+            const totalLines = fileContent.value.split('\n').length;
+            const symbols = Array.isArray(firedSymbols) ? firedSymbols : [];
+            return {
+                success: true,
+                path: input.path,
+                symbols: symbols.map(formatSymbol),
+                symbolContext: buildSymbolContext(symbols, totalLines),
+                message: symbols.length > 0
+                    ? 'Symbols returned from the background language-feature command.'
+                    : 'No model was loaded after background LSP activation.'
+            };
+        }
+        // 2. Wait for providers to register
+        let providers = context.languageFeaturesService?.documentSymbolProvider.ordered(model) ?? [];
+        if (providers.length === 0) {
+            for (let i = 0; i < 10; i++) {
+                await new Promise(resolve => setTimeout(resolve, 200));
+                providers = context.languageFeaturesService?.documentSymbolProvider.ordered(model) ?? [];
+                if (providers.length > 0)
+                    break;
+            }
+        }
+        if (providers.length === 0 && (!Array.isArray(firedSymbols) || firedSymbols.length === 0)) {
+            return {
+                success: true,
+                path: input.path,
+                symbols: [],
+                symbolContext: [],
+                message: 'No semantic symbol providers found after firing the language server for this file type.'
+            };
+        }
+        const allSymbols = providers.length === 0 && Array.isArray(firedSymbols) ? [...firedSymbols] : [];
+        const token = cancellationTokenFromAbortSignal(context.signal);
+        for (const provider of providers) {
+            const result = await provider.provideDocumentSymbols(model, token);
+            if (result) {
+                allSymbols.push(...result);
+            }
+        }
+        const symbolContext = buildSymbolContext(allSymbols, model.getLineCount());
+        return {
+            success: true,
+            path: input.path,
+            symbols: allSymbols.map(formatSymbol),
+            symbolContext
+        };
+    }
+};
+function formatSymbol(s) {
+    return {
+        name: s.name,
+        kind: s.kind,
+        kindLabel: symbolKindToLabel(s.kind),
+        range: {
+            start: s.range.startLineNumber,
+            end: s.range.endLineNumber
+        },
+        selectionRange: {
+            start: s.selectionRange.startLineNumber,
+            end: s.selectionRange.endLineNumber
+        },
+        children: s.children?.map(formatSymbol)
+    };
+}
+//# sourceMappingURL=ReadSymbolsTool.js.map

package/dist/tools/ReadSymbolsTool.js.map

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

package/dist/tools/SearchCodebaseTool.d.ts

@@ -0,0 +1,6 @@
+import { CleanSlateTool } from './types.js';
+/**
+ * Tool: search_codebase (Semantic Search / RAG)
+ */
+export declare const searchCodebaseTool: CleanSlateTool;
+//# sourceMappingURL=SearchCodebaseTool.d.ts.map