@roackb2/heddle 0.0.2

package/dist/src/tools/edit-file.js

@@ -0,0 +1,268 @@
+// ---------------------------------------------------------------------------
+// Tool: edit_file
+// ---------------------------------------------------------------------------
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+const DIFF_CONTEXT_LINES = 2;
+const MAX_DIFF_PREVIEW_LINES = 80;
+export const editFileTool = {
+    name: 'edit_file',
+    description: 'Edit a file directly inside the current workspace without going through shell redirection or heredocs. Prefer this over shell commands when you need to create or change file contents. Use { "path", "oldText", "newText" } for an exact replacement, optionally with replaceAll, or use { "path", "content", "createIfMissing" } to overwrite an existing file or create a new one explicitly. This tool only writes inside the current workspace root and returns a structured edit summary.',
+    requiresApproval: true,
+    parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Workspace-relative path to the file to edit',
+            },
+            oldText: {
+                type: 'string',
+                description: 'Existing text to replace exactly',
+            },
+            newText: {
+                type: 'string',
+                description: 'Replacement text for oldText',
+            },
+            replaceAll: {
+                type: 'boolean',
+                description: 'Replace every matching occurrence instead of requiring a single exact match',
+            },
+            content: {
+                type: 'string',
+                description: 'Full file content to write',
+            },
+            createIfMissing: {
+                type: 'boolean',
+                description: 'Allow creating the file if it does not already exist when using content',
+            },
+        },
+        required: ['path'],
+    },
+    async execute(raw) {
+        if (!isEditFileInput(raw)) {
+            return {
+                ok: false,
+                error: 'Invalid input for edit_file. Use either { "path", "oldText", "newText", "replaceAll?" } or { "path", "content", "createIfMissing?" }.',
+            };
+        }
+        const workspaceRoot = process.cwd();
+        const targetPath = resolve(raw.path);
+        if (!isInsideWorkspace(workspaceRoot, targetPath)) {
+            return {
+                ok: false,
+                error: `edit_file only writes inside the current workspace root (${workspaceRoot}). Refusing to modify ${targetPath}.`,
+            };
+        }
+        if ('content' in raw) {
+            return writeFileContent(raw, workspaceRoot, targetPath);
+        }
+        return replaceFileContent(raw, workspaceRoot, targetPath);
+    },
+};
+async function writeFileContent(input, workspaceRoot, targetPath) {
+    const existed = await pathExists(targetPath);
+    const previousContent = existed ? await readFile(targetPath, 'utf8') : '';
+    if (!existed && !input.createIfMissing) {
+        return {
+            ok: false,
+            error: `File does not exist: ${targetPath}. Set createIfMissing to true if you want edit_file to create it.`,
+        };
+    }
+    await mkdir(dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, input.content, 'utf8');
+    return {
+        ok: true,
+        output: {
+            path: toWorkspacePath(workspaceRoot, targetPath),
+            action: existed ? 'overwritten' : 'created',
+            bytesWritten: Buffer.byteLength(input.content, 'utf8'),
+            diff: buildDiffPreview(previousContent, input.content, toWorkspacePath(workspaceRoot, targetPath), existed ? 'overwritten' : 'created'),
+        },
+    };
+}
+async function replaceFileContent(input, workspaceRoot, targetPath) {
+    let current;
+    try {
+        current = await readFile(targetPath, 'utf8');
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: `Failed to read ${targetPath}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const matchCount = countOccurrences(current, input.oldText);
+    if (matchCount === 0) {
+        return {
+            ok: false,
+            error: `edit_file could not find the requested oldText in ${targetPath}. Read the file again and provide an exact match.`,
+        };
+    }
+    if (matchCount > 1 && !input.replaceAll) {
+        return {
+            ok: false,
+            error: `edit_file found ${matchCount} matches for oldText in ${targetPath}. Refine oldText or set replaceAll to true.`,
+        };
+    }
+    const nextContent = input.replaceAll ? current.split(input.oldText).join(input.newText) : replaceFirst(current, input.oldText, input.newText);
+    await writeFile(targetPath, nextContent, 'utf8');
+    return {
+        ok: true,
+        output: {
+            path: toWorkspacePath(workspaceRoot, targetPath),
+            action: 'replaced',
+            matchCount,
+            bytesWritten: Buffer.byteLength(nextContent, 'utf8'),
+            diff: buildDiffPreview(current, nextContent, toWorkspacePath(workspaceRoot, targetPath), 'replaced'),
+        },
+    };
+}
+export async function previewEditFileInput(raw, workspaceRoot = process.cwd()) {
+    if (!isEditFileInput(raw)) {
+        return undefined;
+    }
+    const targetPath = resolve(raw.path);
+    if (!isInsideWorkspace(workspaceRoot, targetPath)) {
+        return undefined;
+    }
+    const workspacePath = toWorkspacePath(workspaceRoot, targetPath);
+    if ('content' in raw) {
+        const existed = await pathExists(targetPath);
+        if (!existed && !raw.createIfMissing) {
+            return undefined;
+        }
+        const previousContent = existed ? await readFile(targetPath, 'utf8') : '';
+        return buildDiffPreview(previousContent, raw.content, workspacePath, existed ? 'overwritten' : 'created');
+    }
+    let current;
+    try {
+        current = await readFile(targetPath, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const matchCount = countOccurrences(current, raw.oldText);
+    if (matchCount === 0 || (matchCount > 1 && !raw.replaceAll)) {
+        return undefined;
+    }
+    const nextContent = raw.replaceAll ? current.split(raw.oldText).join(raw.newText) : replaceFirst(current, raw.oldText, raw.newText);
+    return buildDiffPreview(current, nextContent, workspacePath, 'replaced');
+}
+function isEditFileInput(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return false;
+    }
+    const input = raw;
+    const keys = Object.keys(input);
+    const allowedKeys = new Set(['path', 'oldText', 'newText', 'replaceAll', 'content', 'createIfMissing']);
+    if (keys.some((key) => !allowedKeys.has(key))) {
+        return false;
+    }
+    if (typeof input.path !== 'string' || !input.path.trim()) {
+        return false;
+    }
+    const hasReplaceShape = typeof input.oldText === 'string' && typeof input.newText === 'string';
+    const hasWriteShape = typeof input.content === 'string';
+    if (hasReplaceShape === hasWriteShape) {
+        return false;
+    }
+    if (hasReplaceShape) {
+        return input.replaceAll === undefined || typeof input.replaceAll === 'boolean';
+    }
+    return input.createIfMissing === undefined || typeof input.createIfMissing === 'boolean';
+}
+function isInsideWorkspace(workspaceRoot, targetPath) {
+    const rel = relative(workspaceRoot, targetPath);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+function countOccurrences(content, search) {
+    if (!search) {
+        return 0;
+    }
+    let count = 0;
+    let index = 0;
+    while (true) {
+        const nextIndex = content.indexOf(search, index);
+        if (nextIndex === -1) {
+            return count;
+        }
+        count++;
+        index = nextIndex + search.length;
+    }
+}
+function replaceFirst(content, search, replacement) {
+    const index = content.indexOf(search);
+    if (index === -1) {
+        return content;
+    }
+    return `${content.slice(0, index)}${replacement}${content.slice(index + search.length)}`;
+}
+function toWorkspacePath(workspaceRoot, targetPath) {
+    const rel = relative(workspaceRoot, targetPath);
+    return rel || '.';
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function buildDiffPreview(previousContent, nextContent, path, action) {
+    const previousLines = splitLines(previousContent);
+    const nextLines = splitLines(nextContent);
+    const prefix = countCommonPrefix(previousLines, nextLines);
+    const suffix = countCommonSuffix(previousLines, nextLines, prefix);
+    const previousChangedEnd = previousLines.length - suffix;
+    const nextChangedEnd = nextLines.length - suffix;
+    const contextStart = Math.max(0, prefix - DIFF_CONTEXT_LINES);
+    const previousContextEnd = Math.min(previousLines.length, previousChangedEnd + DIFF_CONTEXT_LINES);
+    const nextContextEnd = Math.min(nextLines.length, nextChangedEnd + DIFF_CONTEXT_LINES);
+    const lines = [
+        `--- ${action === 'created' ? '/dev/null' : `a/${path}`}`,
+        `+++ b/${path}`,
+        `@@ -${formatHunkRange(contextStart + 1, previousContextEnd - contextStart)} +${formatHunkRange(contextStart + 1, nextContextEnd - contextStart)} @@`,
+        ...previousLines.slice(contextStart, prefix).map((line) => ` ${line}`),
+        ...previousLines.slice(prefix, previousChangedEnd).map((line) => `-${line}`),
+        ...nextLines.slice(prefix, nextChangedEnd).map((line) => `+${line}`),
+        ...nextLines.slice(nextChangedEnd, nextContextEnd).map((line) => ` ${line}`),
+    ];
+    if (lines.length <= MAX_DIFF_PREVIEW_LINES) {
+        return { path, action, diff: lines.join('\n'), truncated: false };
+    }
+    const truncatedLines = [
+        ...lines.slice(0, MAX_DIFF_PREVIEW_LINES - 1),
+        '... diff preview truncated ...',
+    ];
+    return { path, action, diff: truncatedLines.join('\n'), truncated: true };
+}
+function splitLines(content) {
+    if (!content) {
+        return [];
+    }
+    return content.replace(/\r\n/g, '\n').split('\n').slice(0, content.endsWith('\n') ? -1 : undefined);
+}
+function countCommonPrefix(previousLines, nextLines) {
+    let index = 0;
+    while (index < previousLines.length && index < nextLines.length && previousLines[index] === nextLines[index]) {
+        index++;
+    }
+    return index;
+}
+function countCommonSuffix(previousLines, nextLines, prefix) {
+    let count = 0;
+    while (previousLines.length - count - 1 >= prefix &&
+        nextLines.length - count - 1 >= prefix &&
+        previousLines[previousLines.length - count - 1] === nextLines[nextLines.length - count - 1]) {
+        count++;
+    }
+    return count;
+}
+function formatHunkRange(start, length) {
+    return length === 1 ? `${start}` : `${start},${length}`;
+}
+//# sourceMappingURL=edit-file.js.map

package/dist/src/tools/edit-file.js.map

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

package/dist/src/tools/execute-tool.d.ts

@@ -0,0 +1,8 @@
+import type { ToolCall, ToolResult } from '../types.js';
+import type { ToolRegistry } from './registry.js';
+/**
+ * Execute a tool call against the registry.
+ * Wraps execution in try/catch and applies a timeout.
+ */
+export declare function executeTool(registry: ToolRegistry, call: ToolCall, timeoutMs?: number): Promise<ToolResult>;
+//# sourceMappingURL=execute-tool.d.ts.map

package/dist/src/tools/execute-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-tool.d.ts","sourceRoot":"","sources":["../../../src/tools/execute-tool.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAIlD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,QAAQ,EACd,SAAS,GAAE,MAA2B,GACrC,OAAO,CAAC,UAAU,CAAC,CAuBrB"}

package/dist/src/tools/execute-tool.js

@@ -0,0 +1,31 @@
+// ---------------------------------------------------------------------------
+// Tool Executor
+// ---------------------------------------------------------------------------
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Execute a tool call against the registry.
+ * Wraps execution in try/catch and applies a timeout.
+ */
+export async function executeTool(registry, call, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const tool = registry.get(call.tool);
+    if (!tool) {
+        return {
+            ok: false,
+            error: `Unknown tool: ${call.tool}. Available tools: ${registry.names().join(', ')}`,
+        };
+    }
+    try {
+        const result = await Promise.race([
+            tool.execute(call.input),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Tool "${call.tool}" timed out after ${timeoutMs}ms`)), timeoutMs)),
+        ]);
+        return result;
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+//# sourceMappingURL=execute-tool.js.map

package/dist/src/tools/execute-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-tool.js","sourceRoot":"","sources":["../../../src/tools/execute-tool.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAK9E,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAsB,EACtB,IAAc,EACd,YAAoB,kBAAkB;IAEtC,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,iBAAiB,IAAI,CAAC,IAAI,sBAAsB,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;SACrF,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YAChC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;YACxB,IAAI,OAAO,CAAa,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CACpC,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,IAAI,CAAC,IAAI,qBAAqB,SAAS,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,CACrG;SACF,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,EAAE,EAAE,KAAK;YACT,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/src/tools/list-files.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../types.js';
+export declare const listFilesTool: ToolDefinition;
+//# sourceMappingURL=list-files.d.ts.map

package/dist/src/tools/list-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-files.d.ts","sourceRoot":"","sources":["../../../src/tools/list-files.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AAM9D,eAAO,MAAM,aAAa,EAAE,cAiC3B,CAAC"}

package/dist/src/tools/list-files.js

@@ -0,0 +1,49 @@
+// ---------------------------------------------------------------------------
+// Tool: list_files
+// ---------------------------------------------------------------------------
+import { readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+export const listFilesTool = {
+    name: 'list_files',
+    description: 'List files and directories inside a directory path. Use this to inspect folders, not to read file contents. Prefer this when you need an initial view of the workspace or want to explore an obvious nearby folder before using broader search. Relative paths are resolved from the current working directory and may also point to nearby parent or sibling folders, such as "..". Defaults to the current working directory. Returns a flat newline-separated list of entry names; directories end with /. Example inputs: { "path": "." }, { "path": ".." }',
+    parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Directory path to list. Defaults to "."',
+            },
+        },
+    },
+    async execute(raw) {
+        if (!isListFilesInput(raw)) {
+            return { ok: false, error: 'Invalid input for list_files. Allowed fields: path. Example: { "path": "." }' };
+        }
+        const input = raw;
+        const dir = resolve(input.path ?? '.');
+        try {
+            const entries = await readdir(dir, { withFileTypes: true });
+            const names = entries.map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
+            return { ok: true, output: names.join('\n') };
+        }
+        catch (err) {
+            if (err instanceof Error && 'code' in err && err.code === 'ENOTDIR') {
+                return { ok: false, error: `Failed to list ${dir}: path is a file, not a directory. Use read_file for file contents.` };
+            }
+            return { ok: false, error: `Failed to list ${dir}: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    },
+};
+function isListFilesInput(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return false;
+    }
+    const input = raw;
+    const keys = Object.keys(input);
+    if (keys.some((key) => key !== 'path')) {
+        return false;
+    }
+    return input.path === undefined || typeof input.path === 'string';
+}
+//# sourceMappingURL=list-files.js.map

package/dist/src/tools/list-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-files.js","sourceRoot":"","sources":["../../../src/tools/list-files.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C,IAAI,EAAE,YAAY;IAClB,WAAW,EACT,iiBAAiiB;IACniB,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,oBAAoB,EAAE,KAAK;QAC3B,UAAU,EAAE;YACV,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,yCAAyC;aACvD;SACF;KACF;IACD,KAAK,CAAC,OAAO,CAAC,GAAY;QACxB,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,8EAA8E,EAAE,CAAC;QAC9G,CAAC;QAED,MAAM,KAAK,GAAmB,GAAG,CAAC;QAClC,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC;QAEvC,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAC5E,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,KAAK,IAAI,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBACpE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,GAAG,qEAAqE,EAAE,CAAC;YAC1H,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,kBAAkB,GAAG,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QAC5G,CAAC;IACH,CAAC;CACF,CAAC;AAEF,SAAS,gBAAgB,CAAC,GAAY;IACpC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAG,GAA8B,CAAC;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,MAAM,CAAC,EAAE,CAAC;QACvC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;AACpE,CAAC"}

package/dist/src/tools/read-file.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../types.js';
+export declare const readFileTool: ToolDefinition;
+//# sourceMappingURL=read-file.d.ts.map

package/dist/src/tools/read-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-file.d.ts","sourceRoot":"","sources":["../../../src/tools/read-file.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AAQ9D,eAAO,MAAM,YAAY,EAAE,cAuD1B,CAAC"}

package/dist/src/tools/read-file.js

@@ -0,0 +1,73 @@
+// ---------------------------------------------------------------------------
+// Tool: read_file
+// ---------------------------------------------------------------------------
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+export const readFileTool = {
+    name: 'read_file',
+    description: 'Read the contents of a file. Use this when you already know the file path and want its contents, not when you want to inspect a directory. Relative paths are resolved from the current working directory and may also point to nearby parent or sibling folders. Optionally limit returned lines with maxLines and start from a 0-based line offset with offset, which is useful for paging through long files. Returns the file text directly, or just the selected window when maxLines and/or offset are provided. Example inputs: { "path": "path/to/file.txt" }, { "path": "../shared-notes/summary.md" }, { "path": "src/run-agent.ts", "offset": 200, "maxLines": 120 }',
+    parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            path: {
+                type: 'string',
+                description: 'Path to the file to read',
+            },
+            maxLines: {
+                type: 'number',
+                description: 'Maximum number of lines to return',
+            },
+            offset: {
+                type: 'number',
+                description: '0-based line offset to start reading from',
+            },
+        },
+        required: ['path'],
+    },
+    async execute(raw) {
+        if (!isReadFileInput(raw)) {
+            return { ok: false, error: 'Invalid input for read_file. Required field: path. Optional fields: maxLines, offset.' };
+        }
+        const input = raw;
+        const filePath = resolve(input.path);
+        try {
+            const content = await readFile(filePath, 'utf-8');
+            const lines = content.split('\n');
+            const start = input.offset && input.offset > 0 ? Math.floor(input.offset) : 0;
+            if ((input.maxLines && input.maxLines > 0) || start > 0) {
+                const end = input.maxLines && input.maxLines > 0 ? start + Math.floor(input.maxLines) : undefined;
+                const windowedLines = lines.slice(start, end);
+                const joined = windowedLines.join('\n');
+                if (content.endsWith('\n') && windowedLines.length > 0 && end !== undefined && end < lines.length) {
+                    return { ok: true, output: joined };
+                }
+                return { ok: true, output: joined };
+            }
+            return { ok: true, output: content };
+        }
+        catch (err) {
+            if (err instanceof Error && 'code' in err && err.code === 'EISDIR') {
+                return { ok: false, error: `Failed to read ${filePath}: path is a directory, not a file. Use list_files to inspect directories.` };
+            }
+            return { ok: false, error: `Failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    },
+};
+function isReadFileInput(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return false;
+    }
+    const input = raw;
+    const keys = Object.keys(input);
+    if (keys.some((key) => key !== 'path' && key !== 'maxLines' && key !== 'offset')) {
+        return false;
+    }
+    if (typeof input.path !== 'string') {
+        return false;
+    }
+    const validMaxLines = input.maxLines === undefined || typeof input.maxLines === 'number';
+    const validOffset = input.offset === undefined || typeof input.offset === 'number';
+    return validMaxLines && validOffset;
+}
+//# sourceMappingURL=read-file.js.map

package/dist/src/tools/read-file.js.map

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

package/dist/src/tools/registry.d.ts

@@ -0,0 +1,11 @@
+import type { ToolDefinition } from '../types.js';
+export type ToolRegistry = {
+    get(name: string): ToolDefinition | undefined;
+    list(): ToolDefinition[];
+    names(): string[];
+};
+/**
+ * Create a registry from an array of tool definitions.
+ */
+export declare function createToolRegistry(tools: ToolDefinition[]): ToolRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/tools/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/tools/registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG;IACzB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAC9C,IAAI,IAAI,cAAc,EAAE,CAAC;IACzB,KAAK,IAAI,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,YAAY,CAoBxE"}

package/dist/src/tools/registry.js

@@ -0,0 +1,27 @@
+// ---------------------------------------------------------------------------
+// Tool Registry
+// ---------------------------------------------------------------------------
+/**
+ * Create a registry from an array of tool definitions.
+ */
+export function createToolRegistry(tools) {
+    const map = new Map();
+    for (const tool of tools) {
+        if (map.has(tool.name)) {
+            throw new Error(`Duplicate tool name: ${tool.name}`);
+        }
+        map.set(tool.name, tool);
+    }
+    return {
+        get(name) {
+            return map.get(name);
+        },
+        list() {
+            return [...map.values()];
+        },
+        names() {
+            return [...map.keys()];
+        },
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/tools/registry.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAU9E;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAuB;IACxD,MAAM,GAAG,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACvD,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,OAAO;QACL,GAAG,CAAC,IAAY;YACd,OAAO,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;QACD,IAAI;YACF,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3B,CAAC;QACD,KAAK;YACH,OAAO,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QACzB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/src/tools/report-state.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from '../types.js';
+export declare const reportStateTool: ToolDefinition;
+//# sourceMappingURL=report-state.d.ts.map

package/dist/src/tools/report-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-state.d.ts","sourceRoot":"","sources":["../../../src/tools/report-state.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AAQ9D,eAAO,MAAM,eAAe,EAAE,cAmC7B,CAAC"}

package/dist/src/tools/report-state.js

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// Tool: report_state
+// Record current rationale, uncertainty, or missing needs in a structured way.
+// ---------------------------------------------------------------------------
+export const reportStateTool = {
+    name: 'report_state',
+    description: 'Report your current reasoning state in a structured way. Use this when you are blocked, uncertain, missing information, recovering from repeated low-value exploration, or about to take a speculative path. This does not inspect or change the environment. It records what is missing and the single most important next thing you need. Use it to tell the library author what capability, input, or support was missing so future agents are less likely to get stuck on the same problem. Returns the same structured report back. Example input: { "rationale": "I need to inspect the top-level directory first.", "missing": ["Top-level directory contents"], "nextNeed": "list_files on ." }',
+    parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            rationale: {
+                type: 'string',
+                description: 'Why you are taking or considering the next step',
+            },
+            missing: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Information or evidence you are missing',
+            },
+            nextNeed: {
+                type: 'string',
+                description: 'The single most important next thing you need, such as a tool call, input, or piece of evidence',
+            },
+        },
+        required: ['rationale'],
+    },
+    async execute(raw) {
+        if (!isReportStateInput(raw)) {
+            return {
+                ok: false,
+                error: 'Invalid input for report_state. Required field: rationale. Optional fields: missing, nextNeed.',
+            };
+        }
+        return { ok: true, output: raw };
+    },
+};
+function isReportStateInput(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return false;
+    }
+    const input = raw;
+    const keys = Object.keys(input);
+    if (keys.some((key) => key !== 'rationale' &&
+        key !== 'missing' &&
+        key !== 'nextNeed')) {
+        return false;
+    }
+    if (typeof input.rationale !== 'string') {
+        return false;
+    }
+    if (input.missing !== undefined && !isStringArray(input.missing)) {
+        return false;
+    }
+    if (input.nextNeed !== undefined && typeof input.nextNeed !== 'string') {
+        return false;
+    }
+    return true;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+//# sourceMappingURL=report-state.js.map

package/dist/src/tools/report-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-state.js","sourceRoot":"","sources":["../../../src/tools/report-state.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,qBAAqB;AACrB,+EAA+E;AAC/E,8EAA8E;AAU9E,MAAM,CAAC,MAAM,eAAe,GAAmB;IAC7C,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,yqBAAyqB;IAC3qB,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ;QACd,oBAAoB,EAAE,KAAK;QAC3B,UAAU,EAAE;YACV,SAAS,EAAE;gBACT,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,iDAAiD;aAC/D;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,yCAAyC;aACvD;YACD,QAAQ,EAAE;gBACR,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,iGAAiG;aAC/G;SACF;QACD,QAAQ,EAAE,CAAC,WAAW,CAAC;KACxB;IACD,KAAK,CAAC,OAAO,CAAC,GAAY;QACxB,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EACH,gGAAgG;aACnG,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IACnC,CAAC;CACF,CAAC;AAEF,SAAS,kBAAkB,CAAC,GAAY;IACtC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAG,GAA8B,CAAC;IAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,IACE,IAAI,CAAC,IAAI,CACP,CAAC,GAAG,EAAE,EAAE,CACN,GAAG,KAAK,WAAW;QACnB,GAAG,KAAK,SAAS;QACjB,GAAG,KAAK,UAAU,CACrB,EACD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACjE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACvE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC;AACjF,CAAC"}