@cleanslate/sdk 0.1.0

package/dist/tools/UpdateTodoTool.js

@@ -0,0 +1,116 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) CleanSlate. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+function normalizeStatus(status) {
+    const normalized = typeof status === 'string' ? status.trim().toLowerCase() : '';
+    if (normalized === 'completed' || normalized === 'complete' || normalized === 'done') {
+        return 'completed';
+    }
+    if (normalized === 'in_progress' || normalized === 'in-progress' || normalized === 'doing' || normalized === 'active') {
+        return 'in_progress';
+    }
+    return 'pending';
+}
+function normalizeText(text) {
+    return text
+        .replace(/^\s*[-*]?\s*\[[xX/\s]\]\s*/, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function statusPrefix(status) {
+    if (status === 'completed') {
+        return '[x]';
+    }
+    if (status === 'in_progress') {
+        return '[/]';
+    }
+    return '[ ]';
+}
+/**
+ * Tool: update_todo
+ */
+export const updateTodoTool = {
+    name: 'update_todo',
+    description: 'Creates or updates the machine-readable task checklist for the current objective. Use before and during multi-step work through a native tool call only; do not write checklist JSON or to_do fences in assistant text. Input: { items: [{ content: string, status: "pending" | "in_progress" | "completed" }] } or { to_do: string[] }. Returns normalized to_do plus completion counts.',
+    parametersSchema: {
+        type: 'object',
+        properties: {
+            items: {
+                type: 'array',
+                description: 'Preferred checklist format.',
+                items: {
+                    type: 'object',
+                    properties: {
+                        content: { type: 'string' },
+                        text: { type: 'string' },
+                        status: {
+                            type: 'string',
+                            enum: ['pending', 'in_progress', 'completed', 'todo', 'doing', 'done']
+                        }
+                    }
+                }
+            },
+            to_do: {
+                type: 'array',
+                description: 'Existing checkbox format such as "[ ] Inspect files", "[/] Editing globals", "[x] Verify".',
+                items: { type: 'string' }
+            },
+            summary: {
+                type: 'string',
+                description: 'Brief reason for the checklist update.'
+            }
+        }
+    },
+    category: 'system',
+    async run(input, _context) {
+        const normalized = [];
+        if (Array.isArray(input.items)) {
+            for (const item of input.items) {
+                const content = normalizeText(String(item?.content ?? item?.text ?? ''));
+                if (!content) {
+                    continue;
+                }
+                normalized.push(`${statusPrefix(normalizeStatus(item?.status))} ${content}`);
+            }
+        }
+        if (normalized.length === 0 && Array.isArray(input.to_do)) {
+            for (const item of input.to_do) {
+                if (typeof item !== 'string') {
+                    continue;
+                }
+                const trimmed = item.trim();
+                if (!trimmed) {
+                    continue;
+                }
+                if (/^\s*[-*]?\s*\[[xX/\s]\]/.test(trimmed)) {
+                    normalized.push(trimmed.replace(/^\s*[-*]\s*/, ''));
+                }
+                else {
+                    normalized.push(`[ ] ${normalizeText(trimmed)}`);
+                }
+            }
+        }
+        const deduped = normalized.filter((item, index, arr) => arr.findIndex(other => normalizeText(other).toLowerCase() === normalizeText(item).toLowerCase()) === index);
+        if (deduped.length === 0) {
+            return {
+                success: false,
+                code: 'empty_todo',
+                message: 'update_todo requires at least one non-empty task item.'
+            };
+        }
+        const completed = deduped.filter(item => /^\s*\[x\]/i.test(item)).length;
+        const inProgress = deduped.filter(item => /^\s*\[\/\]/.test(item)).length;
+        const pending = deduped.length - completed;
+        return {
+            success: true,
+            to_do: deduped,
+            completed,
+            inProgress,
+            pending,
+            allDone: pending === 0,
+            summary: typeof input.summary === 'string' ? input.summary.trim() : undefined
+        };
+    }
+};
+//# sourceMappingURL=UpdateTodoTool.js.map

package/dist/tools/UpdateTodoTool.js.map

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

package/dist/tools/WebRetrievalTools.d.ts

@@ -0,0 +1,4 @@
+import { CleanSlateTool } from './types.js';
+export declare const webSearchTool: CleanSlateTool;
+export declare const webFetchTool: CleanSlateTool;
+//# sourceMappingURL=WebRetrievalTools.d.ts.map

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

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

package/dist/tools/WebRetrievalTools.js

@@ -0,0 +1,169 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) CleanSlate. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+import { cancellationTokenFromAbortSignal } from '../services/cleanSlateCancellation.js';
+const CURRENT_YEAR = new Date().getFullYear();
+export const webSearchTool = {
+    name: 'web_search',
+    description: `Search the public web for current or external information. Use this for discovery when the answer may depend on information outside the workspace or after the model training cutoff. Current year: ${CURRENT_YEAR}. Returns ranked results with URLs/citations; use web_fetch when you need to read a specific result page. Free-only mode uses configured SearXNG first and anonymous hosted MCP fallbacks only when enabled.`,
+    category: 'discovery',
+    parametersSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Concise web search query. Include product/library/version/date terms when freshness matters.'
+            },
+            maxResults: {
+                type: 'number',
+                description: 'Maximum number of ranked results to return. Defaults to CleanSlate web-search settings, capped at 20.'
+            },
+            allowedDomains: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Optional domain allowlist, for example ["docs.python.org", "github.com"]. Wildcards are ignored.'
+            },
+            blockedDomains: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Optional domain blocklist. Wildcards are ignored.'
+            },
+            recencyDays: {
+                type: 'number',
+                description: 'Optional freshness hint in days. Providers may not support hard recency filtering; include date terms in the query too.'
+            }
+        },
+        required: ['query']
+    },
+    async run(input, context) {
+        if (!context.cleanSlateMainService) {
+            return {
+                success: false,
+                code: 'web_retrieval_unavailable',
+                error: 'CleanSlate main service is not available for web_search.'
+            };
+        }
+        const query = input.query?.trim();
+        if (!query) {
+            return {
+                success: false,
+                code: 'missing_query',
+                error: 'web_search requires a non-empty query.'
+            };
+        }
+        const config = await context.configService.getResolvedConfiguration();
+        const webSearch = config.webSearch;
+        if (webSearch?.enabled === false) {
+            return {
+                success: false,
+                code: 'web_search_disabled',
+                error: 'Web search is disabled in CleanSlate settings.'
+            };
+        }
+        const result = await context.cleanSlateMainService.webSearch({
+            query,
+            maxResults: input.maxResults ?? webSearch?.maxResults,
+            providerOrder: normalizeProviderOrder(webSearch?.providerOrder),
+            searxngBaseUrl: webSearch?.searxngBaseUrl,
+            includeAnonymousHostedProviders: webSearch?.includeAnonymousHostedProviders,
+            hardStopOnQuota: webSearch?.hardStopOnQuota,
+            timeoutMs: webSearch?.timeoutMs,
+            recencyDays: input.recencyDays,
+            domains: {
+                allowed: normalizeDomains(input.allowedDomains),
+                blocked: normalizeDomains(input.blockedDomains)
+            }
+        }, cancellationTokenFromAbortSignal(context.signal));
+        return {
+            ...result,
+            freeOnly: webSearch?.mode ?? 'freeOnly',
+            sourcePolicy: 'Use the returned citation URLs when relying on web_search results. Use web_fetch for any page whose content must be inspected directly.'
+        };
+    }
+};
+export const webFetchTool = {
+    name: 'web_fetch',
+    description: 'Fetch and extract a specific public web URL. Use this after web_search or when the user gives a URL. The fetcher runs in the Node process with URL, redirect, DNS/private-network, timeout, size, cache, and content extraction guards. It refuses localhost/private network URLs.',
+    category: 'discovery',
+    parametersSchema: {
+        type: 'object',
+        properties: {
+            url: {
+                type: 'string',
+                description: 'Fully qualified http or https URL to fetch. http is upgraded to https unless allowPlainHttp is true.'
+            },
+            format: {
+                type: 'string',
+                enum: ['markdown', 'text', 'html'],
+                description: 'Return format. Defaults to markdown.'
+            },
+            maxContentCharacters: {
+                type: 'number',
+                description: 'Maximum extracted characters returned to the model. Defaults to 120000 and is capped at 120000.'
+            },
+            allowPlainHttp: {
+                type: 'boolean',
+                description: 'Set true only when the target is known to require plain HTTP. Private/local hosts remain blocked.'
+            }
+        },
+        required: ['url']
+    },
+    async run(input, context) {
+        if (!context.cleanSlateMainService) {
+            return {
+                success: false,
+                code: 'web_retrieval_unavailable',
+                error: 'CleanSlate main service is not available for web_fetch.'
+            };
+        }
+        const url = input.url?.trim();
+        if (!url) {
+            return {
+                success: false,
+                code: 'missing_url',
+                error: 'web_fetch requires a URL.'
+            };
+        }
+        const config = await context.configService.getResolvedConfiguration();
+        if (config.webSearch?.enabled === false) {
+            return {
+                success: false,
+                code: 'web_search_disabled',
+                error: 'Web retrieval is disabled in CleanSlate settings.'
+            };
+        }
+        const result = await context.cleanSlateMainService.webFetch({
+            url,
+            format: normalizeFormat(input.format),
+            timeoutMs: config.webSearch?.timeoutMs,
+            maxContentCharacters: input.maxContentCharacters,
+            allowPlainHttp: input.allowPlainHttp === true
+        }, cancellationTokenFromAbortSignal(context.signal));
+        return {
+            ...result,
+            sourcePolicy: 'When using this fetched content, cite finalUrl or the returned citation URL.'
+        };
+    }
+};
+function normalizeProviderOrder(providerOrder) {
+    if (!Array.isArray(providerOrder)) {
+        return undefined;
+    }
+    const allowed = new Set(['searxng', 'exaMcpAnonymous', 'parallelMcpAnonymous']);
+    const normalized = providerOrder.filter((provider) => allowed.has(provider));
+    return normalized.length > 0 ? Array.from(new Set(normalized)) : undefined;
+}
+function normalizeDomains(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const normalized = Array.from(new Set(value
+        .map(domain => domain.trim())
+        .filter(domain => domain.length > 0 && !domain.includes('*'))));
+    return normalized.length > 0 ? normalized : undefined;
+}
+function normalizeFormat(format) {
+    return format === 'text' || format === 'html' ? format : 'markdown';
+}
+//# sourceMappingURL=WebRetrievalTools.js.map

package/dist/tools/WebRetrievalTools.js.map

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

package/dist/tools/WriteFileTool.d.ts

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

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

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

package/dist/tools/WriteFileTool.js

@@ -0,0 +1,145 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) CleanSlate. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+import { URI } from '../core/uri.js';
+import { Range } from '../core/range.js';
+import { resolvePathToUri, isDocumentationFile, isUriInIdeWorkspace } from './utils.js';
+import { CleanSlateFileHistory } from '../services/cleanSlateFileHistory.js';
+import { applyEditTool } from './ApplyEditTool.js';
+/**
+ * Tool: write_file
+ */
+export const writeFileTool = {
+    name: 'write_file',
+    description: `Writes the complete contents of a file. Creates the file when it does not exist and replaces it when it does.
+Use this for new files and intentional whole-file rewrites. Existing files must have been read in full first; stale or partial reads are rejected. Use apply_edit for localized changes.
+Input: { file_path: string, content: string, open?: boolean }`,
+    category: "edit",
+    parametersSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            file_path: { type: 'string', description: 'The absolute path to create or replace.' },
+            content: { type: 'string', description: 'The complete desired file contents.' },
+            open: { type: 'boolean', description: 'Whether to reveal a newly created file. Defaults to true.' }
+        },
+        required: ['file_path', 'content']
+    },
+    async run(input, context) {
+        const requestedPath = input.file_path ?? input.path;
+        const { content } = input;
+        if (!requestedPath)
+            throw new Error('file_path is required');
+        if (content === undefined || content === null)
+            throw new Error('content is required (use empty string for empty files)');
+        try {
+            const uri = resolvePathToUri(requestedPath, context, { allowWorkspaceRootRelativeAbsolute: false });
+            const exists = !!context.modelService.getModel(uri) || await context.fileService.exists(uri);
+            if (exists) {
+                const result = await applyEditTool.run({
+                    path: requestedPath,
+                    edits: [{ mode: 'full_file', content }],
+                    historyOperation: 'write_file',
+                    historyToolName: writeFileTool.name
+                }, context);
+                if (result?.success === false) {
+                    return {
+                        ...result,
+                        recoveryHint: result.recoveryHint
+                            ?? 'Read the complete current file, then retry write_file with the intended full content.'
+                    };
+                }
+                const beforeContent = typeof result?.beforeContent === 'string'
+                    ? result.beforeContent
+                    : content;
+                const afterContent = typeof result?.afterContent === 'string'
+                    ? result.afterContent
+                    : content;
+                const changed = beforeContent !== afterContent;
+                return {
+                    ...result,
+                    success: true,
+                    persisted: true,
+                    created: false,
+                    updated: changed,
+                    operation: changed ? 'updated' : 'unchanged',
+                    path: uri.fsPath,
+                    beforeContent,
+                    afterContent,
+                    message: changed
+                        ? `Replaced the complete contents of ${uri.fsPath}.`
+                        : `The file ${uri.fsPath} already has the requested contents.`
+                };
+            }
+            // Production semantics: this tool must create the file with its actual content.
+            // Preview-first behavior made the agent believe writes had landed when they had not.
+            const isDoc = isDocumentationFile(requestedPath);
+            const workspaceId = context.workspaceContextService.getWorkspace().id;
+            const storageRoot = context.environmentService ? URI.joinPath(context.environmentService.workspaceStorageHome, workspaceId) : undefined;
+            const historyEntry = await CleanSlateFileHistory.trackEdit({
+                workspaceRoot: context.workspaceContextService.getWorkspaceFolder(uri)?.uri,
+                storageRoot,
+                resource: uri,
+                fileService: context.fileService,
+                modelService: context.modelService,
+                operation: 'write_file',
+                toolName: writeFileTool.name
+            });
+            await context.textFileService.create([{ resource: uri, value: content, options: { overwrite: false } }]);
+            let mtime;
+            try {
+                mtime = (await context.fileService.stat(uri)).mtime;
+            }
+            catch {
+                // Creation succeeded, but metadata may be unavailable for some providers.
+            }
+            context.readFileState?.set(uri.toString(), {
+                path: uri.fsPath,
+                uri: uri.toString(),
+                content,
+                currentVersionId: context.modelService.getModel(uri)?.getVersionId(),
+                mtime,
+                totalLines: content.length > 0 ? content.split('\n').length : 0,
+                isPartialView: false,
+                readAt: Date.now()
+            });
+            // 2. Reveal the new file in the editor only when it belongs to the project the IDE
+            // currently has open. For a cross-project Agent Manager session the file is still
+            // written to disk; it just must not leak into the other project's editor.
+            const revealInEditor = input.open !== false && isUriInIdeWorkspace(context, uri);
+            if (revealInEditor) {
+                await context.codeEditorService.openCodeEditor({
+                    resource: uri,
+                    options: { pinned: true, preserveFocus: false }
+                }, context.codeEditorService.getActiveCodeEditor());
+            }
+            const added = content.length > 0 ? content.split('\n').length : 0;
+            const deleted = 0;
+            if (revealInEditor && !isDoc && content.length > 0) {
+                const range = new Range(1, 1, 1, 1);
+                context.editorDecorationHost?.registerPostApplySession(uri, [{ range, text: content }], [{ range, text: '', originalStartLine: 1 }], '');
+            }
+            return {
+                success: true,
+                created: true,
+                updated: false,
+                persisted: true,
+                operation: 'created',
+                path: uri.fsPath,
+                historyEntryId: historyEntry?.id,
+                added,
+                deleted,
+                beforeContent: '',
+                afterContent: content,
+                message: isDoc
+                    ? `Created documentation file: ${uri.fsPath}`
+                    : `Created file and wrote content to disk: ${uri.fsPath}`
+            };
+        }
+        catch (err) {
+            throw new Error(`Failed to write ${requestedPath}: ${String(err)}`);
+        }
+    }
+};
+//# sourceMappingURL=WriteFileTool.js.map

package/dist/tools/WriteFileTool.js.map

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

package/dist/tools/cleanSlateFileReadPolicy.d.ts

@@ -0,0 +1,33 @@
+/** Tool-output ceiling so one read cannot dominate every later turn. */
+export declare const CLEANSLATE_MAX_FULL_FILE_READ_BYTES: number;
+/** 50 KiB at the conservative three-bytes-per-token source estimate. */
+export declare const CLEANSLATE_ABSOLUTE_MAX_FILE_READ_TOKENS: number;
+/**
+ * Reads never starve below this even when the prompt-size estimate says the
+ * context window is exhausted. The estimate is deliberately conservative
+ * (UTF-8 bytes / 3 overstates real tokenizers), so a hard zero here produced
+ * useless single-digit-byte budgets that stalled agent runs; if the window is
+ * truly full the provider rejects the request and compaction handles it.
+ */
+export declare const CLEANSLATE_MIN_FILE_READ_TOKENS = 2000;
+export declare const CLEANSLATE_MAX_FILE_READ_LINES = 1000;
+export declare const CLEANSLATE_FILE_READ_CONTEXT_FRACTION = 0.15;
+export declare const CLEANSLATE_FILE_READ_AVAILABLE_FRACTION = 0.5;
+/** Conservative provider-independent fallback for source text. */
+export declare const CLEANSLATE_FILE_READ_BYTES_PER_TOKEN = 3;
+export interface ICleanSlateFileReadBudget {
+    maxBytes: number;
+    maxTokens: number;
+    contextWindowTokens: number;
+    availableInputTokens: number;
+}
+export declare function estimateCleanSlateUtf8Bytes(value: string): number;
+export declare function estimateCleanSlateFileReadTokens(value: string): number;
+export declare function resolveCleanSlateFileReadBudget(contextWindowTokens: number, availableInputTokens: number): ICleanSlateFileReadBudget;
+export interface ICleanSlateBoundedLineSlice {
+    content: string;
+    endExclusive: number;
+    oversizedFirstLine: boolean;
+}
+export declare function takeCleanSlateBoundedLineSlice(lines: readonly string[], startIndex: number, endExclusive: number, maxBytes: number): ICleanSlateBoundedLineSlice;
+//# sourceMappingURL=cleanSlateFileReadPolicy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cleanSlateFileReadPolicy.d.ts","sourceRoot":"","sources":["../../src/tools/cleanSlateFileReadPolicy.ts"],"names":[],"mappings":"AAKA,wEAAwE;AACxE,eAAO,MAAM,mCAAmC,QAAY,CAAC;AAC7D,wEAAwE;AACxE,eAAO,MAAM,wCAAwC,QAAqD,CAAC;AAC3G;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,OAAQ,CAAC;AACrD,eAAO,MAAM,8BAA8B,OAAQ,CAAC;AACpD,eAAO,MAAM,qCAAqC,OAAO,CAAC;AAC1D,eAAO,MAAM,uCAAuC,MAAM,CAAC;AAC3D,kEAAkE;AAClE,eAAO,MAAM,oCAAoC,IAAI,CAAC;AAEtD,MAAM,WAAW,yBAAyB;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqBjE;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,+BAA+B,CAC9C,mBAAmB,EAAE,MAAM,EAC3B,oBAAoB,EAAE,MAAM,GAC1B,yBAAyB,CAc3B;AAED,MAAM,WAAW,2BAA2B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,8BAA8B,CAC7C,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACd,2BAA2B,CAuB7B"}

package/dist/tools/cleanSlateFileReadPolicy.js

@@ -0,0 +1,84 @@
+/*---------------------------------------------------------------------------------------------
+ * Copyright (c) CleanSlate. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+/** Tool-output ceiling so one read cannot dominate every later turn. */
+export const CLEANSLATE_MAX_FULL_FILE_READ_BYTES = 50 * 1024;
+/** 50 KiB at the conservative three-bytes-per-token source estimate. */
+export const CLEANSLATE_ABSOLUTE_MAX_FILE_READ_TOKENS = Math.ceil(CLEANSLATE_MAX_FULL_FILE_READ_BYTES / 3);
+/**
+ * Reads never starve below this even when the prompt-size estimate says the
+ * context window is exhausted. The estimate is deliberately conservative
+ * (UTF-8 bytes / 3 overstates real tokenizers), so a hard zero here produced
+ * useless single-digit-byte budgets that stalled agent runs; if the window is
+ * truly full the provider rejects the request and compaction handles it.
+ */
+export const CLEANSLATE_MIN_FILE_READ_TOKENS = 2_000;
+export const CLEANSLATE_MAX_FILE_READ_LINES = 1_000;
+export const CLEANSLATE_FILE_READ_CONTEXT_FRACTION = 0.15;
+export const CLEANSLATE_FILE_READ_AVAILABLE_FRACTION = 0.5;
+/** Conservative provider-independent fallback for source text. */
+export const CLEANSLATE_FILE_READ_BYTES_PER_TOKEN = 3;
+export function estimateCleanSlateUtf8Bytes(value) {
+    let bytes = 0;
+    for (let index = 0; index < value.length; index++) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit < 0x80) {
+            bytes += 1;
+        }
+        else if (codeUnit < 0x800) {
+            bytes += 2;
+        }
+        else if (codeUnit >= 0xD800 && codeUnit <= 0xDBFF && index + 1 < value.length) {
+            const next = value.charCodeAt(index + 1);
+            if (next >= 0xDC00 && next <= 0xDFFF) {
+                bytes += 4;
+                index++;
+            }
+            else {
+                bytes += 3;
+            }
+        }
+        else {
+            bytes += 3;
+        }
+    }
+    return bytes;
+}
+export function estimateCleanSlateFileReadTokens(value) {
+    return Math.ceil(estimateCleanSlateUtf8Bytes(value) / CLEANSLATE_FILE_READ_BYTES_PER_TOKEN);
+}
+export function resolveCleanSlateFileReadBudget(contextWindowTokens, availableInputTokens) {
+    const safeContextWindow = Math.max(1, Math.floor(contextWindowTokens));
+    const safeAvailableInput = Math.max(1, Math.min(safeContextWindow, Math.floor(availableInputTokens)));
+    const maxTokens = Math.max(CLEANSLATE_MIN_FILE_READ_TOKENS, Math.floor(Math.min(CLEANSLATE_ABSOLUTE_MAX_FILE_READ_TOKENS, safeContextWindow * CLEANSLATE_FILE_READ_CONTEXT_FRACTION, safeAvailableInput * CLEANSLATE_FILE_READ_AVAILABLE_FRACTION)));
+    return {
+        maxBytes: Math.min(CLEANSLATE_MAX_FULL_FILE_READ_BYTES, maxTokens * CLEANSLATE_FILE_READ_BYTES_PER_TOKEN),
+        maxTokens,
+        contextWindowTokens: safeContextWindow,
+        availableInputTokens: safeAvailableInput
+    };
+}
+export function takeCleanSlateBoundedLineSlice(lines, startIndex, endExclusive, maxBytes) {
+    const selected = [];
+    let byteCount = 0;
+    for (let index = startIndex; index < endExclusive; index++) {
+        const line = lines[index] ?? '';
+        const additionalBytes = estimateCleanSlateUtf8Bytes(line) + (selected.length > 0 ? 1 : 0);
+        if (byteCount + additionalBytes > maxBytes) {
+            return {
+                content: selected.join('\n'),
+                endExclusive: index,
+                oversizedFirstLine: selected.length === 0
+            };
+        }
+        selected.push(line);
+        byteCount += additionalBytes;
+    }
+    return {
+        content: selected.join('\n'),
+        endExclusive,
+        oversizedFirstLine: false
+    };
+}
+//# sourceMappingURL=cleanSlateFileReadPolicy.js.map

package/dist/tools/cleanSlateFileReadPolicy.js.map

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