@denizokcu/haze 0.0.2 → 0.0.3

package/dist/llm/hazeTools.d.ts

@@ -6,6 +6,13 @@ export declare const hazeTools: {
         includeIgnored: boolean;
         cursor?: string | undefined;
     }, {
+        ok: boolean;
+        toolName: string;
+        path: string | undefined;
+        error: string;
+        recoverable: boolean;
+        suggestedNextStep: string;
+    } | {
         ok: true;
         duplicateSkipped: true;
         toolName: string;
@@ -30,6 +37,13 @@ export declare const hazeTools: {
         offset?: number | undefined;
         limit?: number | undefined;
     }, {
+        ok: boolean;
+        toolName: string;
+        path: string | undefined;
+        error: string;
+        recoverable: boolean;
+        suggestedNextStep: string;
+    } | {
         ok: true;
         duplicateSkipped: true;
         toolName: string;
@@ -60,6 +74,13 @@ export declare const hazeTools: {
         content: string;
         allowIgnored: boolean;
     }, {
+        ok: boolean;
+        toolName: string;
+        path: string | undefined;
+        error: string;
+        recoverable: boolean;
+        suggestedNextStep: string;
+    } | {
         ok: true;
         duplicateSkipped: true;
         toolName: string;
@@ -69,6 +90,8 @@ export declare const hazeTools: {
         path: string;
         startLine: number;
         endLine: number;
+        requestedEndLine: number;
+        endLineClamped: boolean;
         replacementLines: number;
         appended: boolean;
     }>;
@@ -78,6 +101,13 @@ export declare const hazeTools: {
         overwriteExisting: boolean;
         allowIgnored: boolean;
     }, {
+        ok: boolean;
+        toolName: string;
+        path: string | undefined;
+        error: string;
+        recoverable: boolean;
+        suggestedNextStep: string;
+    } | {
         ok: true;
         duplicateSkipped: true;
         toolName: string;
@@ -96,6 +126,13 @@ export declare const hazeTools: {
         }[];
         allowIgnored: boolean;
     }, {
+        ok: boolean;
+        toolName: string;
+        path: string | undefined;
+        error: string;
+        recoverable: boolean;
+        suggestedNextStep: string;
+    } | {
         ok: true;
         duplicateSkipped: true;
         toolName: string;
@@ -104,6 +141,7 @@ export declare const hazeTools: {
         ok: boolean;
         path: string;
         edits: number;
+        approximateMatches: number;
     }>;
     bash: import("ai").Tool<{
         command: string;

package/dist/llm/hazeTools.js

@@ -40,6 +40,60 @@ function truncate(text, maxChars = MAX_OUTPUT_CHARS) {
 function numberLines(lines, startLine) {
     return lines.map((line, index) => `${String(startLine + index).padStart(4, ' ')} | ${line}`).join('\n');
 }
+function stripLineNumberPrefixes(text) {
+    return text.replace(/^\s*\d+\s+\| ?/gm, '');
+}
+function lineStartOffsets(text) {
+    const offsets = [0];
+    for (let index = 0; index < text.length; index++) {
+        if (text[index] === '\n')
+            offsets.push(index + 1);
+    }
+    return offsets;
+}
+function findLineTrimmedRange(original, oldText) {
+    const wantedLines = oldText.replace(/\r\n/g, '\n').split('\n').map(line => line.trimEnd());
+    if (wantedLines.at(-1) === '')
+        wantedLines.pop();
+    if (wantedLines.length === 0)
+        return undefined;
+    const originalLines = original.replace(/\r\n/g, '\n').split('\n');
+    const hasTrailingNewline = original.endsWith('\n');
+    if (hasTrailingNewline)
+        originalLines.pop();
+    const offsets = lineStartOffsets(original);
+    const matches = [];
+    for (let lineIndex = 0; lineIndex <= originalLines.length - wantedLines.length; lineIndex++) {
+        const window = originalLines.slice(lineIndex, lineIndex + wantedLines.length).map(line => line.trimEnd());
+        if (window.every((line, index) => line === wantedLines[index])) {
+            const start = offsets[lineIndex] ?? 0;
+            const endLineIndex = lineIndex + wantedLines.length;
+            const end = endLineIndex < offsets.length ? (offsets[endLineIndex] ?? original.length) : original.length;
+            matches.push({ start, end });
+        }
+    }
+    if (matches.length !== 1)
+        return undefined;
+    return matches[0];
+}
+function findEditRange(original, oldText) {
+    const candidates = [oldText, stripLineNumberPrefixes(oldText)].filter((candidate, index, all) => candidate.length > 0 && all.indexOf(candidate) === index);
+    for (const candidate of candidates) {
+        const first = original.indexOf(candidate);
+        if (first !== -1) {
+            const second = original.indexOf(candidate, first + candidate.length);
+            if (second !== -1)
+                return { kind: 'multiple' };
+            return { kind: 'found', start: first, end: first + candidate.length, approximate: candidate !== oldText };
+        }
+    }
+    for (const candidate of candidates) {
+        const range = findLineTrimmedRange(original, candidate);
+        if (range)
+            return { kind: 'found', ...range, approximate: true };
+    }
+    return { kind: 'missing' };
+}
 function toolCallKey(toolName, input) {
     return `${toolName}:${JSON.stringify(input)}`;
 }
@@ -59,6 +113,13 @@ function inputPath(input) {
         ? input.path
         : undefined;
 }
+function isStructuredFailure(value) {
+    return typeof value === 'object' && value != null && 'ok' in value && value.ok === false;
+}
+function structuredToolFailure(toolName, error, suggestedNextStep, pathForError) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, toolName, path: pathForError, error: message, recoverable: true, suggestedNextStep };
+}
 async function runDedupedTool(toolName, input, context, execute) {
     const ctx = hazeContext(context);
     if (!ctx)
@@ -67,9 +128,18 @@ async function runDedupedTool(toolName, input, context, execute) {
     ctx.completedToolCalls ??= new Map();
     ctx.failedMutationPaths ??= new Set();
     ctx.pathsReadAfterFailedMutation ??= new Set();
+    ctx.inFlightMutationPaths ??= new Set();
     ctx.mutationEpoch ??= 0;
     const key = toolCallKey(toolName, input);
     const pathForInput = inputPath(input);
+    if (isMutatingTool(toolName) && pathForInput && ctx.inFlightMutationPaths.has(pathForInput)) {
+        return {
+            ok: true,
+            duplicateSkipped: true,
+            toolName,
+            reason: `Skipped concurrent mutation for ${pathForInput}. Read the file again, then make one editFile call with all non-overlapping replacements or one replaceLines call based on the latest line numbers.`,
+        };
+    }
     if (isMutatingTool(toolName) && pathForInput && ctx.failedMutationPaths.has(pathForInput) && !ctx.pathsReadAfterFailedMutation.has(pathForInput)) {
         throw new Error(`Read ${pathForInput} before attempting another edit after the previous edit failure.`);
     }
@@ -93,10 +163,19 @@ async function runDedupedTool(toolName, input, context, execute) {
             reason: 'Skipped duplicate in-flight tool call with identical input.',
         };
     }
+    if (isMutatingTool(toolName) && pathForInput)
+        ctx.inFlightMutationPaths.add(pathForInput);
     const promise = execute();
     ctx.inFlightToolCalls.set(key, promise);
     try {
         const result = await promise;
+        if (isStructuredFailure(result)) {
+            if (isMutatingTool(toolName) && pathForInput) {
+                ctx.failedMutationPaths.add(pathForInput);
+                ctx.pathsReadAfterFailedMutation.delete(pathForInput);
+            }
+            return result;
+        }
         if (toolName === 'readFile' && pathForInput)
             ctx.pathsReadAfterFailedMutation.add(pathForInput);
         if (isMutatingTool(toolName)) {
@@ -118,6 +197,8 @@ async function runDedupedTool(toolName, input, context, execute) {
     }
     finally {
         ctx.inFlightToolCalls.delete(key);
+        if (isMutatingTool(toolName) && pathForInput)
+            ctx.inFlightMutationPaths?.delete(pathForInput);
     }
 }
 function looksLikeShellFileMutation(command) {
@@ -136,29 +217,34 @@ export const hazeTools = {
             includeIgnored: z.boolean().default(false).describe('Include files ignored by .gitignore. Use only when explicitly needed.'),
         }),
         execute: async ({ path: dirPath, recursive, maxEntries, cursor, includeIgnored }, context) => runDedupedTool('listFiles', { path: dirPath, recursive, maxEntries, cursor, includeIgnored }, context, async () => {
-            const absolutePath = resolveWorkspacePath(dirPath);
-            await assertNotIgnored(absolutePath, dirPath, includeIgnored);
-            const entries = [];
-            let ignoredSkipped = 0;
-            const walked = await walkDir(absolutePath, { recursive, maxEntries: maxEntries + 1, cursor, filter: async (entry) => {
-                    if (!includeIgnored && await isGitIgnored(entry.absolutePath)) {
-                        ignoredSkipped++;
-                        return false;
+            try {
+                const absolutePath = resolveWorkspacePath(dirPath);
+                await assertNotIgnored(absolutePath, dirPath, includeIgnored);
+                const entries = [];
+                let ignoredSkipped = 0;
+                const walked = await walkDir(absolutePath, { recursive, maxEntries: maxEntries + 1, cursor, filter: async (entry) => {
+                        if (!includeIgnored && await isGitIgnored(entry.absolutePath)) {
+                            ignoredSkipped++;
+                            return false;
+                        }
+                        return true;
+                    } });
+                const page = walked.slice(0, maxEntries);
+                const hasMore = walked.length > maxEntries;
+                for (const entry of page) {
+                    if (entry.isDirectory) {
+                        entries.push({ path: entry.path, type: 'directory' });
+                    }
+                    else if (entry.isFile) {
+                        const stat = await fs.stat(entry.absolutePath);
+                        entries.push({ path: entry.path, type: 'file', size: stat.size });
                     }
-                    return true;
-                } });
-            const page = walked.slice(0, maxEntries);
-            const hasMore = walked.length > maxEntries;
-            for (const entry of page) {
-                if (entry.isDirectory) {
-                    entries.push({ path: entry.path, type: 'directory' });
-                }
-                else if (entry.isFile) {
-                    const stat = await fs.stat(entry.absolutePath);
-                    entries.push({ path: entry.path, type: 'file', size: stat.size });
                 }
+                return { path: dirPath, recursive, includeIgnored, cursor, nextCursor: hasMore ? page.at(-1)?.path : undefined, ignoredSkipped, entries, truncated: hasMore };
+            }
+            catch (error) {
+                return structuredToolFailure('listFiles', error, 'Check that the directory exists and is not ignored, or retry with a narrower path.', dirPath);
             }
-            return { path: dirPath, recursive, includeIgnored, cursor, nextCursor: hasMore ? page.at(-1)?.path : undefined, ignoredSkipped, entries, truncated: hasMore };
         }),
     }),
     readFile: tool({
@@ -170,26 +256,31 @@ export const hazeTools = {
             allowIgnored: z.boolean().default(false).describe('Read the file even if it is ignored by .gitignore. Use only when explicitly needed.'),
         }),
         execute: async ({ path: filePath, offset, limit, allowIgnored }, context) => runDedupedTool('readFile', { path: filePath, offset, limit, allowIgnored }, context, async () => {
-            const absolutePath = resolveWorkspacePath(filePath);
-            await assertNotIgnored(absolutePath, filePath, allowIgnored);
-            const content = await fs.readFile(absolutePath, 'utf8');
-            const lines = content.split(/\r?\n/);
-            const start = offset == null ? 0 : offset - 1;
-            const end = limit == null ? lines.length : start + limit;
-            const selectedLines = lines.slice(start, end);
-            const selected = selectedLines.join('\n');
-            return {
-                path: filePath,
-                startLine: start + 1,
-                endLine: Math.min(end, lines.length),
-                totalLines: lines.length,
-                lineNumberedText: numberLines(selectedLines, start + 1),
-                ...truncate(selected),
-            };
+            try {
+                const absolutePath = resolveWorkspacePath(filePath);
+                await assertNotIgnored(absolutePath, filePath, allowIgnored);
+                const content = await fs.readFile(absolutePath, 'utf8');
+                const lines = content.split(/\r?\n/);
+                const start = offset == null ? 0 : offset - 1;
+                const end = limit == null ? lines.length : start + limit;
+                const selectedLines = lines.slice(start, end);
+                const selected = selectedLines.join('\n');
+                return {
+                    path: filePath,
+                    startLine: start + 1,
+                    endLine: Math.min(end, lines.length),
+                    totalLines: lines.length,
+                    lineNumberedText: numberLines(selectedLines, start + 1),
+                    ...truncate(selected),
+                };
+            }
+            catch (error) {
+                return structuredToolFailure('readFile', error, 'Check the path with listFiles, or set allowIgnored=true only if the user explicitly asked to inspect an ignored file.', filePath);
+            }
         }),
     }),
     replaceLines: tool({
-        description: 'Replace a 1-based inclusive line range in an existing UTF-8 text file. Prefer this after reading a file when exact editFile replacements are ambiguous or fail.',
+        description: 'Replace a 1-based inclusive line range in an existing UTF-8 text file. Prefer this after reading a file when exact editFile replacements are ambiguous or fail. If endLine is slightly beyond EOF, it is clamped to the current last line.',
         inputSchema: z.object({
             path: z.string().describe('File path relative to the current workspace'),
             startLine: z.number().int().positive().describe('First 1-based line number to replace'),
@@ -198,30 +289,34 @@ export const hazeTools = {
             allowIgnored: z.boolean().default(false).describe('Edit the file even if it is ignored by .gitignore. Use only when explicitly needed.'),
         }),
         execute: async ({ path: filePath, startLine, endLine, content, allowIgnored }, context) => runDedupedTool('replaceLines', { path: filePath, startLine, endLine, content, allowIgnored }, context, async () => {
-            const absolutePath = resolveWorkspacePath(filePath);
-            await assertNotIgnored(absolutePath, filePath, allowIgnored);
-            const original = await fs.readFile(absolutePath, 'utf8');
-            const hasTrailingNewline = original.endsWith('\n');
-            const lines = original.split(/\r?\n/);
-            if (hasTrailingNewline)
-                lines.pop();
-            const isAppend = startLine === lines.length + 1 && endLine === lines.length;
-            if (!isAppend && endLine < startLine)
-                throw new Error('endLine must be greater than or equal to startLine, except when appending at EOF with startLine=totalLines+1 and endLine=totalLines');
-            if (startLine > lines.length + 1)
-                throw new Error(`startLine ${startLine} is beyond end of file (${lines.length} lines)`);
-            if (endLine > lines.length)
-                throw new Error(`endLine ${endLine} is beyond end of file (${lines.length} lines)`);
-            const replacementLines = content.length === 0 ? [] : content.split(/\r?\n/);
-            if (isAppend) {
-                lines.push(...replacementLines);
+            try {
+                const absolutePath = resolveWorkspacePath(filePath);
+                await assertNotIgnored(absolutePath, filePath, allowIgnored);
+                const original = await fs.readFile(absolutePath, 'utf8');
+                const hasTrailingNewline = original.endsWith('\n');
+                const lines = original.split(/\r?\n/);
+                if (hasTrailingNewline)
+                    lines.pop();
+                const isAppend = startLine === lines.length + 1 && endLine === lines.length;
+                if (!isAppend && endLine < startLine)
+                    throw new Error('endLine must be greater than or equal to startLine, except when appending at EOF with startLine=totalLines+1 and endLine=totalLines');
+                if (startLine > lines.length + 1)
+                    throw new Error(`startLine ${startLine} is beyond end of file (${lines.length} lines)`);
+                const effectiveEndLine = !isAppend && endLine > lines.length ? lines.length : endLine;
+                const replacementLines = content.length === 0 ? [] : content.split(/\r?\n/);
+                if (isAppend) {
+                    lines.push(...replacementLines);
+                }
+                else {
+                    lines.splice(startLine - 1, effectiveEndLine - startLine + 1, ...replacementLines);
+                }
+                const updated = lines.join('\n') + (hasTrailingNewline ? '\n' : '');
+                await fs.writeFile(absolutePath, updated, 'utf8');
+                return { ok: true, path: filePath, startLine, endLine: effectiveEndLine, requestedEndLine: endLine, endLineClamped: effectiveEndLine !== endLine, replacementLines: replacementLines.length, appended: isAppend };
             }
-            else {
-                lines.splice(startLine - 1, endLine - startLine + 1, ...replacementLines);
+            catch (error) {
+                return structuredToolFailure('replaceLines', error, 'Read the file again for current line numbers, then retry replaceLines with a valid range.', filePath);
             }
-            const updated = lines.join('\n') + (hasTrailingNewline ? '\n' : '');
-            await fs.writeFile(absolutePath, updated, 'utf8');
-            return { ok: true, path: filePath, startLine, endLine, replacementLines: replacementLines.length, appended: isAppend };
         }),
     }),
     writeFile: tool({
@@ -233,26 +328,31 @@ export const hazeTools = {
             allowIgnored: z.boolean().default(false).describe('Write the file even if it is ignored by .gitignore. Use only when explicitly needed.'),
         }),
         execute: async ({ path: filePath, content, overwriteExisting, allowIgnored }, context) => runDedupedTool('writeFile', { path: filePath, content, overwriteExisting, allowIgnored }, context, async () => {
-            const absolutePath = resolveWorkspacePath(filePath);
-            await assertNotIgnored(absolutePath, filePath, allowIgnored);
             try {
-                await fs.access(absolutePath);
-                if (!overwriteExisting) {
-                    throw new Error(`Refusing to overwrite existing file: ${filePath}. Use editFile/replaceLines for targeted edits, or set overwriteExisting=true for an intentional complete rewrite.`);
+                const absolutePath = resolveWorkspacePath(filePath);
+                await assertNotIgnored(absolutePath, filePath, allowIgnored);
+                try {
+                    await fs.access(absolutePath);
+                    if (!overwriteExisting) {
+                        throw new Error(`Refusing to overwrite existing file: ${filePath}. Use editFile/replaceLines for targeted edits, or set overwriteExisting=true for an intentional complete rewrite.`);
+                    }
                 }
+                catch (error) {
+                    const code = typeof error === 'object' && error != null && 'code' in error ? error.code : undefined;
+                    if (code !== 'ENOENT')
+                        throw error;
+                }
+                await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+                await fs.writeFile(absolutePath, content, 'utf8');
+                return { ok: true, path: filePath, bytes: Buffer.byteLength(content, 'utf8'), overwritten: overwriteExisting };
             }
             catch (error) {
-                const code = typeof error === 'object' && error != null && 'code' in error ? error.code : undefined;
-                if (code !== 'ENOENT')
-                    throw error;
+                return structuredToolFailure('writeFile', error, 'Use editFile/replaceLines for existing files, set overwriteExisting=true only for an intentional rewrite, or check the path/ignored-file setting.', filePath);
             }
-            await fs.mkdir(path.dirname(absolutePath), { recursive: true });
-            await fs.writeFile(absolutePath, content, 'utf8');
-            return { ok: true, path: filePath, bytes: Buffer.byteLength(content, 'utf8'), overwritten: overwriteExisting };
         }),
     }),
     editFile: tool({
-        description: 'Edit a text file using exact replacements. Each oldText must match exactly once in the original file and edits must not overlap. If this fails because text is missing or not unique, do not retry; use replaceLines instead.',
+        description: 'Edit a text file using unique replacements. Each oldText should match the current file; line-number prefixes from readFile output and trailing-whitespace-only differences are tolerated when the match is still unique. Put multiple edits to the same file in one call. If this fails because text is missing or not unique, read the file again and use replaceLines.',
         inputSchema: z.object({
             path: z.string().describe('File path relative to the current workspace'),
             edits: z.array(z.object({
@@ -262,29 +362,33 @@ export const hazeTools = {
             allowIgnored: z.boolean().default(false).describe('Edit the file even if it is ignored by .gitignore. Use only when explicitly needed.'),
         }),
         execute: async ({ path: filePath, edits, allowIgnored }, context) => runDedupedTool('editFile', { path: filePath, edits, allowIgnored }, context, async () => {
-            const absolutePath = resolveWorkspacePath(filePath);
-            await assertNotIgnored(absolutePath, filePath, allowIgnored);
-            const original = await fs.readFile(absolutePath, 'utf8');
-            const ranges = edits.map((edit, index) => {
-                const first = original.indexOf(edit.oldText);
-                if (first === -1)
-                    throw new Error(`edit ${index}: oldText was not found`);
-                const second = original.indexOf(edit.oldText, first + edit.oldText.length);
-                if (second !== -1)
-                    throw new Error(`edit ${index}: oldText is not unique`);
-                return { index, start: first, end: first + edit.oldText.length, edit };
-            }).sort((a, b) => a.start - b.start);
-            for (let i = 1; i < ranges.length; i++) {
-                if (ranges[i].start < ranges[i - 1].end) {
-                    throw new Error(`edits ${ranges[i - 1].index} and ${ranges[i].index} overlap`);
+            try {
+                const absolutePath = resolveWorkspacePath(filePath);
+                await assertNotIgnored(absolutePath, filePath, allowIgnored);
+                const original = await fs.readFile(absolutePath, 'utf8');
+                const ranges = edits.map((edit, index) => {
+                    const match = findEditRange(original, edit.oldText);
+                    if (match.kind === 'missing')
+                        throw new Error(`edit ${index}: oldText was not found. Read the file again and use the exact current text, or use replaceLines with the latest line numbers.`);
+                    if (match.kind === 'multiple')
+                        throw new Error(`edit ${index}: oldText is not unique`);
+                    return { index, start: match.start, end: match.end, edit, approximate: match.approximate };
+                }).sort((a, b) => a.start - b.start);
+                for (let i = 1; i < ranges.length; i++) {
+                    if (ranges[i].start < ranges[i - 1].end) {
+                        throw new Error(`edits ${ranges[i - 1].index} and ${ranges[i].index} overlap`);
+                    }
                 }
+                let updated = original;
+                for (const range of [...ranges].sort((a, b) => b.start - a.start)) {
+                    updated = updated.slice(0, range.start) + range.edit.newText + updated.slice(range.end);
+                }
+                await fs.writeFile(absolutePath, updated, 'utf8');
+                return { ok: true, path: filePath, edits: edits.length, approximateMatches: ranges.filter(range => range.approximate).length };
             }
-            let updated = original;
-            for (const range of [...ranges].sort((a, b) => b.start - a.start)) {
-                updated = updated.slice(0, range.start) + range.edit.newText + updated.slice(range.end);
+            catch (error) {
+                return structuredToolFailure('editFile', error, 'Read the file again, then retry with exact current text or use replaceLines with the latest line numbers.', filePath);
             }
-            await fs.writeFile(absolutePath, updated, 'utf8');
-            return { ok: true, path: filePath, edits: edits.length };
         }),
     }),
     bash: tool({
@@ -296,7 +400,7 @@ export const hazeTools = {
         }),
         execute: async ({ command, timeoutSeconds, allowMutation }, context) => runDedupedTool('bash', { command, timeoutSeconds, allowMutation }, context, async () => {
             if (!allowMutation && looksLikeShellFileMutation(command)) {
-                throw new Error('Refusing to mutate files via bash. Use writeFile/editFile/replaceLines, or set allowMutation=true only when shell mutation is explicitly required.');
+                return structuredToolFailure('bash', 'Refusing to mutate files via bash. Use writeFile/editFile/replaceLines, or set allowMutation=true only when shell mutation is explicitly required.', 'Use writeFile/editFile/replaceLines for file changes, or retry bash with allowMutation=true only when shell mutation is explicitly required.');
             }
             const timeoutMs = (timeoutSeconds ?? 60) * 1000;
             return await new Promise(resolve => {

package/dist/llm/initPrompt.js

@@ -1,10 +1,12 @@
 export function buildInitPrompt() {
     return `Initialize this repository for Haze by creating a best-practice AGENTS.md file.
 
-Explore the codebase first, respecting .gitignore:
+Explore the codebase first, respecting .gitignore, but keep this quick and minimal:
 1. Start with exactly one listFiles call from the workspace root. Do not announce that you are starting before the tool call.
-2. After listFiles returns, do not call listFiles with the same input again. Immediately read the files needed to understand project conventions, commands, architecture, and release workflow. Usually read package/config files, README, AGENTS.md if present, and key source entrypoints.
-3. Do not read ignored files unless truly necessary.
+2. Do not use bash for discovery unless package metadata is missing. Do not grep/find the tree for this command.
+3. After listFiles returns, read only the small set needed to understand conventions: package/config files, README, existing AGENTS.md if present, and at most three key source entrypoints/directories.
+4. Do not call listFiles with the same input twice. Do not read the same path repeatedly. Do not read speculative files; list the parent first if unsure.
+5. Aim to finish in 12 tool calls or fewer. Do not read ignored files unless truly necessary.
 
 Create or update AGENTS.md at the workspace root. It should be concise and useful for future coding agents. Include sections when known:
 - Project overview
@@ -15,5 +17,5 @@ Create or update AGENTS.md at the workspace root. It should be concise and usefu
 - Testing/validation expectations
 - Safety notes or files/directories to avoid
 
-If AGENTS.md already exists, preserve useful existing instructions and improve them. After writing it, summarize what you learned and what you wrote.`;
+If AGENTS.md already exists, preserve useful existing instructions and improve them with targeted editFile/replaceLines edits. Do not rewrite the entire file unless it is missing or unusable. After writing it, summarize only the change and validation status.`;
 }

package/dist/llm/systemPrompt.js

@@ -7,8 +7,8 @@ export function buildSystemPrompt(contextFiles = []) {
 Available tools:
 - listFiles: List files and directories in the current workspace. Supports recursive listings and cursor pagination. Prefer this over bash ls/find for project discovery.
 - readFile: Read UTF-8 files with optional line ranges. Returns lineNumberedText for line-based edits.
-- editFile: Edit files with exact unique text replacements. Use only for small, unambiguous replacements.
-- replaceLines: Replace a 1-based inclusive line range. Use when editFile is ambiguous or has failed once. To append at EOF, use startLine=totalLines+1 and endLine=totalLines from the latest readFile result.
+- editFile: Edit files with unique text replacements. Use only for small, unambiguous replacements. Put multiple edits to the same file in one editFile call; do not issue parallel separate edits for the same file.
+- replaceLines: Replace a 1-based inclusive line range. Use when editFile is ambiguous or has failed once. To append at EOF, use startLine=totalLines+1 and endLine=totalLines from the latest readFile result. Slightly-too-large endLine values are clamped to EOF.
 - writeFile: Create files, or overwrite existing files only when overwriteExisting=true is intentionally set for a complete rewrite. Prefer editFile/replaceLines for existing files.
 - bash: Run shell commands for tests, builds, scripts, and inspection that cannot be done with file tools. Do not use bash to mutate files unless explicitly requested or file tools cannot do the job.
 - skill_*: Markdown skills installed in ~/.haze/skills. Use a skill tool when its description matches the user's request; it returns workflow instructions and explicitly referenced files.
@@ -24,7 +24,7 @@ Guidelines:
 - Do not list or read the same path repeatedly unless the file changed or the previous result was insufficient.
 - Read only directly relevant files, usually once. Do not read README/package files unless needed for the task.
 - File tools follow .gitignore by default. Only set includeIgnored/allowIgnored when the user explicitly asks or the task truly requires ignored files, and say why.
-- Prefer editFile for existing files when one small exact replacement is unique.
+- Prefer editFile for existing files when one small replacement is unique. For multiple edits in one file, use one editFile call with multiple non-overlapping edits instead of parallel tool calls.
 - If editFile fails because oldText is missing or not unique, do not retry editFile for the same change; use replaceLines with lineNumberedText from readFile.
 - Use writeFile for new files. For existing files, prefer editFile or replaceLines; only set writeFile overwriteExisting=true when a complete rewrite is intentional and safer than targeted edits.
 - Use bash mainly for tests, builds, package scripts, and commands that are not covered by file tools. Do not combine validation with file mutation in one shell command; use file tools for edits and bash only for validation/inspection.

package/dist/skills/builder/SkillBuilder.d.ts

@@ -9,6 +9,9 @@ type GeneratedSkill = {
 export declare function slug(s: string): string;
 declare function fallbackSkill(description: string): GeneratedSkill;
 declare function withStandardRequirements(content: string): string;
+declare function withSkillName(content: string, name: string): string;
+declare function normalizeSkillDescription(description: string): string;
+declare function withSkillDescription(content: string, description: string): string;
 declare function parseGeneratedSkill(text: string, description: string): GeneratedSkill;
 export declare function createSkill(description: string): Promise<{
     name: string;
@@ -21,5 +24,8 @@ export declare const internals: {
     parseGeneratedSkill: typeof parseGeneratedSkill;
     fallbackSkill: typeof fallbackSkill;
     withStandardRequirements: typeof withStandardRequirements;
+    withSkillName: typeof withSkillName;
+    withSkillDescription: typeof withSkillDescription;
+    normalizeSkillDescription: typeof normalizeSkillDescription;
 };
 export {};