klyro 0.1.1

package/dist/policy/path-guard.js

@@ -0,0 +1,100 @@
+/**
+ * Path safety: ensure every file path the agent touches stays inside `cwd`.
+ *
+ * Refuses:
+ *   - absolute paths outside cwd
+ *   - parent-directory traversal (`..`)
+ *   - symlinks that resolve outside cwd
+ *
+ * Uses `path.resolve` then `path.relative` to check. On Windows, the
+ * comparison is case-insensitive.
+ */
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import { TOOL_ERROR_CODES } from '../tools/normalize.js';
+export class PathGuardError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'PathGuardError';
+    }
+}
+function isWindows() {
+    return process.platform === 'win32';
+}
+function normalizeForCompare(p) {
+    // Realpath resolves symlinks and gives a canonical absolute path.
+    // We don't realpath here (caller does that explicitly when needed).
+    // For the within-cwd check we normalize case on Windows.
+    return isWindows() ? p.toLowerCase() : p;
+}
+/**
+ * Resolve a (possibly relative) path against cwd and assert it stays inside.
+ * Does NOT follow symlinks — call `resolveAndFollowSymlinks` for that.
+ */
+export function resolveWithinCwd(cwd, requested) {
+    if (!requested || requested.length === 0) {
+        throw new PathGuardError(TOOL_ERROR_CODES.INVALID_INPUT, 'Path is empty');
+    }
+    const absCwd = path.resolve(cwd);
+    const resolved = path.isAbsolute(requested) ? path.resolve(requested) : path.resolve(absCwd, requested);
+    // Use relative to test containment. path.relative throws on different
+    // drives on Windows; normalize to handle that.
+    const rel = path.relative(absCwd, resolved);
+    if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))) {
+        return { resolved };
+    }
+    // Different drive on Windows: relative starts with a drive letter
+    if (isWindows() && /^[A-Za-z]:[\\/]/.test(rel)) {
+        throw new PathGuardError(TOOL_ERROR_CODES.PATH_ESCAPE, `Path escapes cwd (different drive): ${requested}`);
+    }
+    throw new PathGuardError(TOOL_ERROR_CODES.PATH_ESCAPE, `Path escapes cwd: ${requested}`);
+}
+/**
+ * Resolve, follow symlinks, and assert the target stays inside cwd.
+ * Use this for read_file / write_file to defeat symlink-based escapes.
+ */
+export async function resolveAndFollowSymlinks(cwd, requested) {
+    const { resolved } = resolveWithinCwd(cwd, requested);
+    let real;
+    let realParent;
+    try {
+        real = await fs.realpath(resolved);
+        realParent = path.dirname(real);
+    }
+    catch {
+        // File doesn't exist yet (e.g. write_file). realpath would fail; fall
+        // back to realpath-ing the parent.
+        const parent = path.dirname(resolved);
+        try {
+            realParent = await fs.realpath(parent);
+        }
+        catch {
+            // Parent doesn't exist either. Don't trust the unresolved parent —
+            // re-validate it against cwd and bail if it's not inside.
+            const { resolved: parentResolved } = resolveWithinCwd(cwd, parent);
+            realParent = parentResolved;
+        }
+        real = path.join(realParent, path.basename(resolved));
+    }
+    const absCwd = await fs.realpath(cwd).catch(() => path.resolve(cwd));
+    const cmpReal = normalizeForCompare(real);
+    const cmpCwd = normalizeForCompare(absCwd);
+    if (cmpReal !== cmpCwd && !cmpReal.startsWith(cmpCwd + path.sep)) {
+        throw new PathGuardError(TOOL_ERROR_CODES.PATH_ESCAPE, `Symlink target escapes cwd: ${requested} -> ${real}`);
+    }
+    // Defense-in-depth: ensure the parent directory of the resolved target
+    // is also inside cwd. This catches the case where the requested path
+    // walks through a symlinked parent (e.g. `<cwd>/evil-link/../escape`)
+    // and `real` happens to land back inside cwd but the parent was outside.
+    // Skip when the target itself is cwd (realParent would be the parent of
+    // cwd, which is necessarily outside).
+    if (real !== absCwd) {
+        const cmpRealParent = normalizeForCompare(realParent);
+        if (cmpRealParent !== cmpCwd && !cmpRealParent.startsWith(cmpCwd + path.sep)) {
+            throw new PathGuardError(TOOL_ERROR_CODES.PATH_ESCAPE, `Path escapes cwd via parent symlink: ${requested} -> ${realParent}`);
+        }
+    }
+    return { resolved: real };
+}

package/dist/policy/secret-redactor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Secret redaction — strip common credential shapes from tool outputs
+ * before they enter the transcript.
+ *
+ * Pattern coverage: AWS access keys, PEM blocks, GitHub tokens, Slack tokens,
+ * generic bearer/JWT, and high-entropy hex strings (best-effort).
+ *
+ * Streaming: we expose `createRedactor()` returning a Transform so large
+ * outputs don't have to buffer in memory.
+ */
+import { Transform } from 'node:stream';
+/** Redact a single string (or Buffer). */
+export declare function redact(input: string | Buffer): string;
+/**
+ * Streaming transform that redacts as bytes flow through. Useful for
+ * piping shell stdout/stderr into the transcript without buffering the
+ * full output in memory.
+ */
+export declare function createRedactor(): Transform;

package/dist/policy/secret-redactor.js

@@ -0,0 +1,52 @@
+/**
+ * Secret redaction — strip common credential shapes from tool outputs
+ * before they enter the transcript.
+ *
+ * Pattern coverage: AWS access keys, PEM blocks, GitHub tokens, Slack tokens,
+ * generic bearer/JWT, and high-entropy hex strings (best-effort).
+ *
+ * Streaming: we expose `createRedactor()` returning a Transform so large
+ * outputs don't have to buffer in memory.
+ */
+import { Transform } from 'node:stream';
+const PATTERNS = [
+    { name: 'aws-key', re: /AKIA[0-9A-Z]{16}/g },
+    { name: 'aws-secret', re: /(?<![A-Za-z0-9])[A-Za-z0-9/+=]{40}(?![A-Za-z0-9])/g },
+    { name: 'pem-block', re: /-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]*?-----END [A-Z ]+PRIVATE KEY-----/g },
+    { name: 'github-token', re: /gh[pousr]_[A-Za-z0-9]{36,255}/g },
+    { name: 'slack-token', re: /xox[abprs]-[A-Za-z0-9-]{10,}/g },
+    { name: 'bearer', re: /Bearer\s+[A-Za-z0-9._\-+/=]{16,}/gi },
+    { name: 'jwt', re: /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g },
+];
+const REPLACEMENT = '[REDACTED]';
+/** Redact a single string (or Buffer). */
+export function redact(input) {
+    const s = typeof input === 'string' ? input : input.toString('utf-8');
+    let out = s;
+    for (const { name, re } of PATTERNS) {
+        out = out.replace(re, `${REPLACEMENT}:${name}`);
+    }
+    return out;
+}
+/**
+ * Streaming transform that redacts as bytes flow through. Useful for
+ * piping shell stdout/stderr into the transcript without buffering the
+ * full output in memory.
+ */
+export function createRedactor() {
+    let buf = '';
+    return new Transform({
+        transform(chunk, _enc, cb) {
+            buf += typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+            // Keep last 1 KiB un-flushed in case a multi-byte pattern straddles
+            // chunk boundaries.
+            const flushEnd = Math.max(0, buf.length - 1024);
+            const flush = buf.slice(0, flushEnd);
+            buf = buf.slice(flushEnd);
+            cb(null, redact(flush));
+        },
+        flush(cb) {
+            cb(null, redact(buf));
+        },
+    });
+}

package/dist/providers.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Provider detection and configuration for the REPL.
+ *
+ * Supports any OpenAI-compatible `/chat/completions` endpoint. When no API
+ * key is set, the REPL probes a list of well-known local servers (Ollama,
+ * LM Studio, vLLM, llama.cpp) and uses whichever responds first.
+ *
+ * Resolution order:
+ *   1. KLYRO_BASE_URL + KLYRO_API_KEY (full manual control)
+ *   2. KLYRO_BASE_URL alone (assume local server, no auth)
+ *   3. Auto-detect a local server
+ *   4. Fall back to api.openai.com with a clear error if no key
+ */
+export interface ProviderConfig {
+    baseURL: string;
+    apiKey: string;
+    model: string;
+    source: 'env' | 'local-probe' | 'manual';
+}
+/** Resolve which provider to use. Does not throw; returns `null` if nothing is reachable. */
+export declare function resolveProvider(): Promise<ProviderConfig | null>;
+/** Pretty-print a hint about how to configure the provider. */
+export declare function providerHelp(p: ProviderConfig | null): string;

package/dist/providers.js

@@ -0,0 +1,83 @@
+/**
+ * Provider detection and configuration for the REPL.
+ *
+ * Supports any OpenAI-compatible `/chat/completions` endpoint. When no API
+ * key is set, the REPL probes a list of well-known local servers (Ollama,
+ * LM Studio, vLLM, llama.cpp) and uses whichever responds first.
+ *
+ * Resolution order:
+ *   1. KLYRO_BASE_URL + KLYRO_API_KEY (full manual control)
+ *   2. KLYRO_BASE_URL alone (assume local server, no auth)
+ *   3. Auto-detect a local server
+ *   4. Fall back to api.openai.com with a clear error if no key
+ */
+import { assertSafeBaseURL, normalizeBaseURL } from './chat.js';
+const LOCAL_ENDPOINTS = [
+    { name: 'Ollama', baseURL: 'http://localhost:11434/v1', defaultModel: 'llama3.2' },
+    { name: 'LM Studio', baseURL: 'http://localhost:1234/v1', defaultModel: 'local-model' },
+    { name: 'vLLM', baseURL: 'http://localhost:8000/v1', defaultModel: 'meta-llama/Llama-3-8B-Instruct' },
+    { name: 'llama.cpp', baseURL: 'http://localhost:8080/v1', defaultModel: 'local-model' },
+];
+/** Resolve which provider to use. Does not throw; returns `null` if nothing is reachable. */
+export async function resolveProvider() {
+    const envBaseURL = process.env.KLYRO_BASE_URL;
+    const envKey = process.env.KLYRO_API_KEY;
+    const envModel = process.env.KLYRO_MODEL;
+    if (envBaseURL) {
+        assertSafeBaseURL(envBaseURL);
+        return {
+            baseURL: normalizeBaseURL(envBaseURL),
+            apiKey: envKey ?? '',
+            model: envModel ?? 'gpt-4o-mini',
+            source: 'env',
+        };
+    }
+    if (envKey) {
+        return {
+            baseURL: normalizeBaseURL('https://api.openai.com/v1'),
+            apiKey: envKey,
+            model: envModel ?? 'gpt-4o-mini',
+            source: 'manual',
+        };
+    }
+    // Probe local endpoints
+    for (const ep of LOCAL_ENDPOINTS) {
+        if (await probeLocal(ep.baseURL)) {
+            return {
+                baseURL: ep.baseURL,
+                apiKey: '',
+                model: envModel ?? ep.defaultModel,
+                source: 'local-probe',
+            };
+        }
+    }
+    return null;
+}
+/** Hit a cheap endpoint to check if a local server is up. */
+async function probeLocal(baseURL) {
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), 600);
+        // Try the OpenAI-style /models endpoint; some servers (Ollama before load)
+        // answer /, others only /v1/models.
+        const res = await fetch(`${baseURL.replace(/\/+$/, '')}/models`, {
+            method: 'GET',
+            signal: ctrl.signal,
+        });
+        clearTimeout(t);
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** Pretty-print a hint about how to configure the provider. */
+export function providerHelp(p) {
+    if (p?.source === 'local-probe') {
+        return `(connected to local ${p.baseURL}, model: ${p.model})`;
+    }
+    if (p?.source === 'env') {
+        return `(env: ${p.baseURL}, model: ${p.model})`;
+    }
+    return `(no provider configured — set KLYRO_BASE_URL + KLYRO_API_KEY, or run a local server like Ollama)`;
+}

package/dist/repl.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Interactive REPL. Reads prompts from stdin one line at a time.
+ *
+ * Conversation history lives in memory only; each new prompt is sent with the
+ * full history so the model can refer back to earlier turns.
+ *
+ * Type ':quit' (or Ctrl-C / Ctrl-D) to exit.
+ */
+export declare function repl(system: string): Promise<void>;

package/dist/repl.js

@@ -0,0 +1,170 @@
+/**
+ * Interactive REPL. Reads prompts from stdin one line at a time.
+ *
+ * Conversation history lives in memory only; each new prompt is sent with the
+ * full history so the model can refer back to earlier turns.
+ *
+ * Type ':quit' (or Ctrl-C / Ctrl-D) to exit.
+ */
+import * as readline from 'node:readline/promises';
+import { stdin, exit } from 'node:process';
+import { streamToStdout, readBoundedText } from './chat.js';
+import { resolveProvider, providerHelp } from './providers.js';
+/** Cap conversation history so we don't blow the model's context window. */
+const MAX_HISTORY_TURNS = 40;
+/** Approximate char budget for the user side of history. */
+const MAX_HISTORY_CHARS = 80_000;
+export async function repl(system) {
+    const provider = await resolveProvider();
+    if (!provider) {
+        console.error('klyro: no provider available.');
+        console.error('  Set KLYRO_BASE_URL and KLYRO_API_KEY, or run a local server (Ollama, LM Studio, vLLM).');
+        console.error('  Examples:');
+        console.error('    set KLYRO_BASE_URL=https://api.openai.com/v1');
+        console.error('    set KLYRO_API_KEY=sk-...');
+        console.error('    ollama serve   # then KLYRO_BASE_URL=http://localhost:11434/v1 KLYRO_MODEL=llama3.2');
+        exit(2);
+    }
+    const { baseURL, apiKey, model, source } = provider;
+    const history = [];
+    // Adapt readline to the environment. On a TTY we let readline manage the
+    // prompt and echo so the user sees their typing; on a pipe we suppress both
+    // because the consumer is a script, not a human.
+    const isTTY = Boolean(stdin.isTTY);
+    const rl = readline.createInterface({
+        input: stdin,
+        output: isTTY ? process.stdout : undefined,
+        terminal: isTTY,
+    });
+    // Ctrl-C: when readline is in TTY mode it intercepts SIGINT and emits a
+    // 'SIGINT' event on the interface. Wire it to a clean exit so the user gets
+    // exit code 130 (the conventional 128+SIGINT(2)) instead of a crash.
+    rl.on('SIGINT', () => {
+        process.stdout.write('\n');
+        rl.close();
+        exit(130);
+    });
+    if (isTTY)
+        console.log(`klyro REPL — type :quit to exit, :clear to reset history  ${providerHelp(provider)}`);
+    try {
+        while (true) {
+            // In TTY mode, readline handles the prompt and echoes the user's typing.
+            // In non-TTY mode, we write the prompt ourselves.
+            if (!isTTY)
+                process.stdout.write('> ');
+            let line;
+            try {
+                // Pass the prompt only when readline is in charge (TTY). In non-TTY
+                // mode the prompt is suppressed (output: undefined) so passing '' is
+                // equivalent and avoids doubling.
+                line = await rl.question(isTTY ? '> ' : '');
+            }
+            catch (err) {
+                // EOF on stdin (Ctrl-D) or close — exit cleanly.
+                break;
+            }
+            if (!line)
+                break; // empty line on EOF
+            const prompt = line.trim();
+            if (!prompt)
+                continue;
+            if (prompt === ':quit' || prompt === ':exit')
+                break;
+            if (prompt === ':clear') {
+                history.length = 0;
+                if (isTTY)
+                    console.log('(history cleared)');
+                continue;
+            }
+            history.push({ role: 'user', content: prompt });
+            trimHistory(history);
+            const reply = await ask(baseURL, apiKey, model, system, history);
+            history.push({ role: 'assistant', content: reply });
+            // streamToStdout already ends with a newline; no extra needed.
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Drop oldest turns to stay under the size cap. */
+function trimHistory(history) {
+    while (history.length > MAX_HISTORY_TURNS)
+        history.shift();
+    let total = 0;
+    for (const t of history)
+        total += t.content.length;
+    while (total > MAX_HISTORY_CHARS && history.length > 2) {
+        const head = history[0];
+        if (!head)
+            break;
+        total -= head.content.length;
+        history.shift();
+    }
+}
+/** Send the full history, stream the reply, return the assistant text. */
+async function ask(baseURL, apiKey, model, system, history) {
+    const ac = new AbortController();
+    const timeoutMs = Number(process.env.KLYRO_TIMEOUT_MS) || 60_000;
+    const t = setTimeout(() => ac.abort(new Error(`request timed out after ${timeoutMs}ms`)), timeoutMs);
+    let res;
+    try {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        // Only attach Authorization when a key is configured. Local servers
+        // (Ollama, LM Studio) accept requests without auth.
+        if (apiKey) {
+            headers['Authorization'] = `Bearer ${apiKey}`;
+        }
+        res = await fetch(`${baseURL.replace(/\/+$/, '')}/chat/completions`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({
+                model,
+                // System message once, at the head of the messages array.
+                messages: [{ role: 'system', content: system }, ...history],
+                stream: true,
+            }),
+            signal: ac.signal,
+        });
+    }
+    catch (err) {
+        clearTimeout(t);
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`\nklyro: request failed: ${msg}`);
+        return '';
+    }
+    clearTimeout(t);
+    if (!res.ok) {
+        const text = await readBoundedText(res.body, 4000);
+        console.error(`\nklyro: HTTP ${res.status} ${res.statusText}\n${text}`);
+        return '';
+    }
+    if (!res.body) {
+        console.error('\nklyro: no response body');
+        return '';
+    }
+    // Use the shared streamToStdout from chat.ts. Capture what we wrote so we
+    // can return it for the conversation history.
+    const collected = [];
+    const origWrite = process.stdout.write.bind(process.stdout);
+    process.stdout.write = (chunk) => {
+        if (typeof chunk === 'string')
+            collected.push(chunk);
+        return origWrite(chunk);
+    };
+    try {
+        await streamToStdout(res.body, ac.signal);
+    }
+    catch (err) {
+        if (!ac.signal.aborted) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`\nklyro: stream error: ${msg}`);
+        }
+    }
+    finally {
+        process.stdout.write = origWrite;
+    }
+    return collected.join('');
+}

package/dist/repl.js.map

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

package/dist/tools/fs/edit-file.d.ts

@@ -0,0 +1,48 @@
+/**
+ * edit_file — find-and-replace in an existing file.
+ * Strict: ambiguous matches fail unless replaceAll=true. Missing match fails.
+ */
+import { z } from 'zod';
+declare const InputSchema: z.ZodObject<{
+    path: z.ZodString;
+    find: z.ZodString;
+    replace: z.ZodString;
+    replaceAll: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export interface EditFileOutput {
+    path: string;
+    replacements: number;
+    diff: string;
+}
+export declare const editFileTool: import("../types.js").Tool<{
+    path: string;
+    find: string;
+    replace: string;
+    replaceAll?: boolean | undefined;
+}, {
+    readonly ok: false;
+    readonly error: {
+        readonly code: "MATCH_NOT_FOUND";
+        readonly message: `find substring not present in ${string}`;
+    };
+    path?: undefined;
+    replacements?: undefined;
+    diff?: undefined;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: "MATCH_AMBIGUOUS";
+        readonly message: `find substring occurs ${number} times in ${string}. Supply more context or pass replaceAll=true.`;
+    };
+    path?: undefined;
+    replacements?: undefined;
+    diff?: undefined;
+} | {
+    path: string;
+    replacements: number;
+    diff: string;
+    readonly ok?: undefined;
+    readonly error?: undefined;
+}>;
+export type EditFileInput = z.infer<typeof InputSchema>;
+export {};

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

@@ -0,0 +1,84 @@
+/**
+ * edit_file — find-and-replace in an existing file.
+ * Strict: ambiguous matches fail unless replaceAll=true. Missing match fails.
+ */
+import * as fs from 'node:fs/promises';
+import { z } from 'zod';
+import { defineTool } from '../types.js';
+import { resolveAndFollowSymlinks } from '../../policy/path-guard.js';
+import { safe } from '../normalize.js';
+const InputSchema = z.object({
+    path: z.string().min(1),
+    find: z.string().min(1).describe('Exact substring to match. Not a regex.'),
+    replace: z.string(),
+    replaceAll: z.boolean().optional().describe('If true, replace every occurrence.'),
+});
+export const editFileTool = defineTool({
+    name: 'edit_file',
+    description: 'Replace a substring in a file. Strict: if `find` is missing or ambiguous, the edit fails (unless replaceAll=true).',
+    inputSchema: InputSchema,
+    execute: async (input, ctx) => {
+        return safe(async () => {
+            const { resolved } = await resolveAndFollowSymlinks(ctx.cwd, input.path);
+            const original = await fs.readFile(resolved, 'utf-8');
+            const count = countOccurrences(original, input.find);
+            if (count === 0) {
+                return {
+                    ok: false,
+                    error: { code: 'MATCH_NOT_FOUND', message: `find substring not present in ${input.path}` },
+                };
+            }
+            const replaceAll = input.replaceAll === true;
+            if (!replaceAll && count > 1) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'MATCH_AMBIGUOUS',
+                        message: `find substring occurs ${count} times in ${input.path}. Supply more context or pass replaceAll=true.`,
+                    },
+                };
+            }
+            const next = replaceAll ? original.split(input.find).join(input.replace) : original.replace(input.find, input.replace);
+            const tmp = `${resolved}.klyro-edit-${process.pid}-${Date.now()}.tmp`;
+            await fs.writeFile(tmp, next, 'utf-8');
+            try {
+                await fs.rename(tmp, resolved);
+            }
+            catch (err) {
+                await fs.unlink(tmp).catch(() => undefined);
+                throw err;
+            }
+            return {
+                path: input.path,
+                replacements: replaceAll ? count : 1,
+                diff: simpleDiff(original, input.find, input.replace, replaceAll ? count : 1),
+            };
+        });
+    },
+});
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let from = 0;
+    while (true) {
+        const i = haystack.indexOf(needle, from);
+        if (i < 0)
+            break;
+        count++;
+        from = i + needle.length;
+    }
+    return count;
+}
+function simpleDiff(original, find, replace, count) {
+    const firstIdx = original.indexOf(find);
+    if (firstIdx < 0)
+        return '';
+    const start = Math.max(0, original.lastIndexOf('\n', firstIdx) + 1);
+    const endLf = original.indexOf('\n', firstIdx + find.length);
+    const end = endLf < 0 ? original.length : endLf;
+    const beforeSnippet = original.slice(start, end);
+    const afterSnippet = beforeSnippet.split(find).join(replace);
+    const more = count > 1 ? `\n... and ${count - 1} more replacement(s)` : '';
+    return `--- before\n${beforeSnippet}\n+++ after\n${afterSnippet}${more}`;
+}

package/dist/tools/fs/list-dir.d.ts

@@ -0,0 +1,40 @@
+/**
+ * list_directory — list entries inside a directory.
+ *
+ * Refuses paths outside cwd. Skips node_modules and .git by default.
+ */
+import { z } from 'zod';
+declare const InputSchema: z.ZodObject<{
+    path: z.ZodDefault<z.ZodString>;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+    skip: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export interface ListEntry {
+    name: string;
+    type: 'file' | 'directory' | 'symlink' | 'other';
+    size: number;
+}
+export interface ListDirOutput {
+    path: string;
+    entries: ListEntry[];
+}
+export declare const listDirTool: import("../types.js").Tool<{
+    path: string;
+    maxDepth?: number | undefined;
+    skip?: string[] | undefined;
+}, {
+    readonly ok: false;
+    readonly error: {
+        readonly code: "INVALID_INPUT";
+        readonly message: `Not a directory: ${string}`;
+    };
+    path?: undefined;
+    entries?: undefined;
+} | {
+    path: string;
+    entries: ListEntry[];
+    readonly ok?: undefined;
+    readonly error?: undefined;
+}>;
+export type ListDirInput = z.infer<typeof InputSchema>;
+export {};