maestro-agent-sdk 0.1.7 → 0.1.9

package/dist/tools/builtin/glob.js

@@ -41,34 +41,42 @@ export const globTool = {
     schema: {
         name: "Glob",
         description: "Fast file pattern matching. Supports `*` (within-segment wildcard), " +
-            "`**` (cross-segment wildcard), `?` (one char). Returns absolute paths " +
-            "sorted by modification time descending — recently-touched files first. " +
-            "Does NOT skip dotfiles or build dirs; the model's pattern is authoritative. " +
-            "Caps results at 10,000 entries (truncates with a note when exceeded).",
+            "`**` (cross-segment wildcard), `?` (one char), `[abc]` / `[a-z]` / `[!abc]` " +
+            "character classes, and `{a,b}` brace expansion (nestable). Returns " +
+            "absolute paths sorted by modification time descending — recently-touched " +
+            "files first. Does NOT skip dotfiles or build dirs; the model's pattern is " +
+            "authoritative. Caps results at 10,000 entries (truncates with a note when exceeded).",
         input_schema: {
             type: "object",
             properties: {
                 pattern: {
                     type: "string",
-                    description: "Glob pattern. Examples: `**/*.ts`, `src/**/*.tsx`, `README.md`, " +
-                        "`config/*.json`. Matched against paths relative to `path`.",
+                    description: "Glob pattern. Examples: `**/*.ts`, `src/**/*.{js,ts,tsx}`, " +
+                        "`file[0-9].log`, `README.md`, `config/*.json`. May also embed " +
+                        "the absolute root (e.g. `/abs/path/**/*.ts`) — in that case " +
+                        "`path` is auto-derived from the fixed prefix and the trailing " +
+                        "portion becomes the matcher.",
                 },
                 path: {
                     type: "string",
                     description: "Optional absolute directory to search in. Defaults to the SDK's process cwd. " +
-                        "Relative paths are rejected.",
+                        "If omitted and `pattern` is absolute, the walk root is auto-extracted " +
+                        "from `pattern`. Relative paths are rejected.",
                 },
             },
             required: ["pattern"],
         },
     },
     async execute(input) {
-        const pattern = typeof input.pattern === "string" ? input.pattern : "";
-        if (!pattern) {
+        const rawPattern = typeof input.pattern === "string" ? input.pattern : "";
+        if (!rawPattern) {
             return JSON.stringify({ error: "Glob: missing 'pattern' argument" });
         }
         const rawPath = typeof input.path === "string" ? input.path : undefined;
         let root;
+        // `pattern` is what compileGlob() consumes. We may rewrite it below when
+        // the caller passed an absolute path inside `pattern` (claude SDK parity).
+        let pattern = rawPattern;
         if (rawPath !== undefined) {
             if (!isAbsolute(rawPath)) {
                 return JSON.stringify({
@@ -77,6 +85,17 @@ export const globTool = {
             }
             root = rawPath;
         }
+        else if (isAbsolute(rawPattern)) {
+            // claude-SDK parity: when the caller embeds the absolute root inside
+            // `pattern` (e.g. `/Users/foo/proj/**/*.ts`) and omits `path`, we split
+            // off the longest fixed prefix and use that as the walk root. Without
+            // this the regex compiled from the absolute pattern matches against
+            // *relative* paths and returns zero — a footgun we hit often when the
+            // model copy-pastes absolute paths it just got from Read/Grep.
+            const split = splitAbsolutePattern(rawPattern);
+            root = split.root;
+            pattern = split.pattern;
+        }
         else {
             root = process.cwd();
         }
@@ -186,15 +205,23 @@ export const globTool = {
  * path (anchored at both ends).
  *
  * Handled tokens:
- *   `**\/`  → `(?:.*\/)?` — zero or more path segments (greedy across `/`)
- *   `**`    → `.*`        — anything including `/`
- *   `*`     → `[^/]*`     — anything except `/` within one segment
- *   `?`     → `[^/]`      — single char within one segment
+ *   `**\/`     → `(?:.*\/)?` — zero or more path segments (greedy across `/`)
+ *   `**`       → `.*`        — anything including `/`
+ *   `*`        → `[^/]*`     — anything except `/` within one segment
+ *   `?`        → `[^/]`      — single char within one segment
+ *   `[abc]`    → `[abc]`     — character class (POSIX `[!abc]` → `[^abc]`)
+ *   `{a,b}`    → `(?:a|b)`   — brace expansion (nestable, body recursively
+ *                              compiled so wildcards / classes inside each
+ *                              alternative still work)
  *
  * Other regex metacharacters are escaped so literals like `.` in `foo.ts`
  * don't accidentally turn into "any char".
  */
 export function compileGlob(pattern) {
+    return new RegExp(`^${compileGlobBody(pattern)}$`);
+}
+/** Build the regex body (no anchors) so brace alternatives can recurse. */
+function compileGlobBody(pattern) {
     let s = "";
     let i = 0;
     while (i < pattern.length) {
@@ -220,6 +247,41 @@ export function compileGlob(pattern) {
             s += "[^/]";
             i += 1;
         }
+        else if (c === "[") {
+            // Character class `[abc]`, `[a-z]`, `[!abc]`. Find the closing `]`;
+            // if missing, treat the `[` as a literal (matches bash defensively).
+            const end = pattern.indexOf("]", i + 1);
+            if (end === -1) {
+                s += "\\[";
+                i += 1;
+            }
+            else {
+                let cls = pattern.slice(i + 1, end);
+                if (cls.startsWith("!"))
+                    cls = `^${cls.slice(1)}`; // POSIX negation
+                s += `[${cls}]`;
+                i = end + 1;
+            }
+        }
+        else if (c === "{") {
+            // Brace expansion `{a,b,c}`. Find the matching `}` accounting for
+            // nesting (`{a,{b,c}}`). On unbalanced braces we treat the `{` as a
+            // literal — bash does the same.
+            const close = matchingBraceClose(pattern, i);
+            if (close === -1) {
+                s += "\\{";
+                i += 1;
+            }
+            else {
+                const body = pattern.slice(i + 1, close);
+                const parts = splitTopLevel(body, ",");
+                // Recursively compile each alternative so a brace can carry full
+                // glob syntax inside (`{*.ts,src/**/*.tsx}` works).
+                const alts = parts.map((p) => compileGlobBody(p));
+                s += `(?:${alts.join("|")})`;
+                i = close + 1;
+            }
+        }
         else if (REGEX_META.includes(c)) {
             s += `\\${c}`;
             i += 1;
@@ -229,7 +291,92 @@ export function compileGlob(pattern) {
             i += 1;
         }
     }
-    return new RegExp(`^${s}$`);
+    return s;
+}
+/**
+ * Locate the `}` that closes the `{` at `openIdx`, respecting nesting.
+ * Returns -1 if the brace is unbalanced (caller falls back to literal).
+ */
+function matchingBraceClose(pattern, openIdx) {
+    let depth = 1;
+    for (let j = openIdx + 1; j < pattern.length; j++) {
+        const ch = pattern[j];
+        if (ch === "{")
+            depth++;
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0)
+                return j;
+        }
+    }
+    return -1;
+}
+/**
+ * Split `body` by `sep` only when the separator appears at the top level
+ * (depth-0 with respect to `{}` nesting). `{a,{b,c}}` splits into
+ * `["a", "{b,c}"]` — not `["a", "{b", "c}"]`.
+ */
+function splitTopLevel(body, sep) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let k = 0; k < body.length; k++) {
+        const ch = body[k];
+        if (ch === "{")
+            depth++;
+        else if (ch === "}")
+            depth--;
+        else if (ch === sep && depth === 0) {
+            parts.push(body.slice(start, k));
+            start = k + 1;
+        }
+    }
+    parts.push(body.slice(start));
+    return parts;
+}
+const REGEX_META = ".+^$()|\\";
+/**
+ * Split an absolute glob pattern into (root, relativePattern).
+ *
+ * claude-SDK accepts patterns like `/Users/foo/proj/**\/*.ts` directly —
+ * its implementation pulls out the longest fixed-segment prefix as the
+ * walk root and uses the rest as the matcher. We mirror that here so the
+ * model's pretrained instinct works without forcing the caller to split
+ * `path` and `pattern` manually.
+ *
+ * Algorithm:
+ *   - Split the pattern by `/`. The leading `/` produces an empty first
+ *     segment.
+ *   - Find the first segment that contains a wildcard meta (`*` or `?`).
+ *   - Everything strictly before it forms the root (rejoined with `/`).
+ *     Everything from that segment onward is the new pattern (relative
+ *     to root).
+ *   - If no segment contains a wildcard the pattern is a literal absolute
+ *     path; treat dirname as the root and basename as the pattern so
+ *     `Glob({pattern: "/etc/hosts"})` still matches the single file.
+ *   - Empty root collapses to "/" (POSIX absolute root).
+ */
+export function splitAbsolutePattern(p) {
+    const segs = p.split("/");
+    let wildAt = -1;
+    for (let i = 0; i < segs.length; i++) {
+        if (segs[i].includes("*") || segs[i].includes("?")) {
+            wildAt = i;
+            break;
+        }
+    }
+    if (wildAt === -1) {
+        // No wildcard — split dirname/basename so literal absolute paths still
+        // match. `Glob({pattern: "/etc/hosts"})` → root "/etc", pattern "hosts".
+        const parts = segs.slice();
+        const last = parts.pop() ?? "";
+        const root = parts.join("/") || "/";
+        return { root, pattern: last };
+    }
+    const rootJoined = segs.slice(0, wildAt).join("/");
+    return {
+        root: rootJoined || "/",
+        pattern: segs.slice(wildAt).join("/"),
+    };
 }
-const REGEX_META = ".+^$()[]{}|\\";
 //# sourceMappingURL=glob.js.map

package/dist/tools/builtin/glob.js.map

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

package/dist/tools/builtin/multi_edit.d.ts

@@ -0,0 +1,16 @@
+import type { FileStateTracker } from "../../tools/file-state.js";
+import type { ToolHandler } from "../../tools/registry.js";
+export interface MultiEditToolOptions {
+    /**
+     * Per-session file-state tracker. When provided, MultiEdit enforces the
+     * Read-before-Edit invariant: the path must have been Read in this session
+     * AND its mtime/size must still match the recorded values.
+     */
+    tracker?: FileStateTracker;
+}
+export declare function createMultiEditTool(opts?: MultiEditToolOptions): ToolHandler;
+/** Backwards-compatible singleton (no tracker — Read-before-Edit gate off). */
+export declare const multiEditTool: ToolHandler;
+export declare const __MAX_FILE_BYTES: number;
+export declare const __MAX_EDITS = 64;
+//# sourceMappingURL=multi_edit.d.ts.map

package/dist/tools/builtin/multi_edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi_edit.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/multi_edit.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAqDpD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,oBAAyB,GAAG,WAAW,CAsNhF;AAED,+EAA+E;AAC/E,eAAO,MAAM,aAAa,EAAE,WAAmC,CAAC;AA8BhE,eAAO,MAAM,gBAAgB,QAAiB,CAAC;AAC/C,eAAO,MAAM,WAAW,KAAY,CAAC"}

package/dist/tools/builtin/multi_edit.js

@@ -0,0 +1,286 @@
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { countOccurrences } from "../../tools/builtin/edit.js";
+/**
+ * MultiEdit builtin — claude SDK `MultiEdit` tool parity for maestro.
+ *
+ * Applies an ordered list of (old_string, new_string) replacements to a
+ * single file **atomically**. The contract that makes this tool valuable:
+ *
+ *   1. Read the file once.
+ *   2. Apply edits sequentially to the in-memory buffer — each edit sees
+ *      the state left by the previous one (so a follow-up edit can target
+ *      text inserted by the previous step).
+ *   3. If ANY edit fails (`old_string` not found, ambiguous match without
+ *      `replace_all`, no-op replacement) we abort BEFORE writing. The
+ *      file on disk is left untouched. The model then sees a structured
+ *      `failedAt: <index>` payload it can react to without having to
+ *      reason about which earlier edits did or didn't land.
+ *   4. Only after all edits succeed do we write once.
+ *
+ * Why a separate tool (rather than have the model call `Edit` in a loop):
+ *
+ *   - Halves API round-trips for the common "fix N spots in one file"
+ *     refactor — the model emits one tool call instead of N.
+ *   - Atomic-by-default eliminates a real class of bug where edit #3 of
+ *     5 fails and the file is left with edits 1–2 applied but the model
+ *     thinks the whole batch is done.
+ *   - The Read-before-Edit gate fires once for the whole batch instead
+ *     of forcing a re-Read between each step.
+ *
+ * Same constraints as Edit:
+ *   - file_path must be absolute.
+ *   - File must exist (MultiEdit never creates — use Write for that).
+ *   - Each edit's `old_string` must occur exactly once in the current
+ *     buffer unless `replace_all: true` is passed for that edit.
+ *   - `old_string === new_string` is rejected as a no-op.
+ *   - 10MB cap on file size (matches Edit / Read).
+ *
+ * Returns a short summary (`File edited: <path> (N edits, M total replacements)`)
+ * followed by a line-numbered preview of the region around the first edit's
+ * new_string — same shape Edit returns post-edit, kept consistent so the
+ * model's verification instinct transfers.
+ */
+const MAX_FILE_BYTES = 10 * 1024 * 1024; // 10MB — same cap as Read / Edit
+const MAX_EDITS = 64; // ceiling on edits per call; prevents pathological batches
+const PREVIEW_LINES_AROUND = 3;
+export function createMultiEditTool(opts = {}) {
+    const { tracker } = opts;
+    return {
+        schema: {
+            name: "MultiEdit",
+            description: "Apply multiple find-and-replace edits to a single file atomically. " +
+                "Each `edits[i].old_string` is matched against the buffer state left " +
+                "by the previous edit, so chained edits can target inserted text. " +
+                "If any edit fails (not found, ambiguous, or no-op) the file is left " +
+                "untouched and a `failedAt` index is returned. file_path must be " +
+                "absolute and the file must already exist (use Write for new files).",
+            input_schema: {
+                type: "object",
+                properties: {
+                    file_path: {
+                        type: "string",
+                        description: "Absolute path to the file. MultiEdit never creates new files.",
+                    },
+                    edits: {
+                        type: "array",
+                        description: "Ordered list of edits to apply. Capped at 64 entries per call. " +
+                            "Each edit obeys the same uniqueness contract as the single-Edit tool " +
+                            "unless its own `replace_all: true` is set.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                old_string: {
+                                    type: "string",
+                                    description: "Exact text to find in the current buffer. Must be non-empty.",
+                                },
+                                new_string: {
+                                    type: "string",
+                                    description: "Replacement text. Must differ from old_string.",
+                                },
+                                replace_all: {
+                                    type: "boolean",
+                                    description: "When true, replace every occurrence in the current buffer. " +
+                                        "Default false (unique-match required).",
+                                },
+                            },
+                            required: ["old_string", "new_string"],
+                        },
+                    },
+                },
+                required: ["file_path", "edits"],
+            },
+        },
+        async execute(input) {
+            const filePath = typeof input.file_path === "string" ? input.file_path : "";
+            if (!filePath) {
+                return JSON.stringify({ error: "MultiEdit: missing 'file_path' argument" });
+            }
+            if (!isAbsolute(filePath)) {
+                return JSON.stringify({
+                    error: `MultiEdit: file_path must be absolute, got '${filePath}'`,
+                });
+            }
+            // Read-before-Edit gate. Fires once for the whole batch.
+            if (tracker) {
+                const gateErr = tracker.checkBeforeMutate(filePath, "MultiEdit");
+                if (gateErr) {
+                    return JSON.stringify({ error: gateErr });
+                }
+            }
+            const rawEdits = input.edits;
+            if (!Array.isArray(rawEdits) || rawEdits.length === 0) {
+                return JSON.stringify({
+                    error: "MultiEdit: 'edits' must be a non-empty array",
+                });
+            }
+            if (rawEdits.length > MAX_EDITS) {
+                return JSON.stringify({
+                    error: `MultiEdit: 'edits' length ${rawEdits.length} exceeds cap of ${MAX_EDITS}. Split into multiple calls.`,
+                });
+            }
+            // Validate every edit up-front so we don't perform a partial dry-run
+            // before realising one edit is malformed. The validation block only
+            // checks shape — the per-edit `old_string` existence check happens
+            // during the apply loop because it depends on prior edits.
+            const edits = [];
+            for (let i = 0; i < rawEdits.length; i++) {
+                const e = rawEdits[i];
+                if (e === null || typeof e !== "object" || Array.isArray(e)) {
+                    return JSON.stringify({
+                        error: `MultiEdit: edit[${i}] must be an object`,
+                    });
+                }
+                const rec = e;
+                if (typeof rec.old_string !== "string") {
+                    return JSON.stringify({
+                        error: `MultiEdit: edit[${i}].old_string must be a string, got ${typeof rec.old_string}`,
+                    });
+                }
+                if (typeof rec.new_string !== "string") {
+                    return JSON.stringify({
+                        error: `MultiEdit: edit[${i}].new_string must be a string, got ${typeof rec.new_string}`,
+                    });
+                }
+                if (rec.old_string.length === 0) {
+                    return JSON.stringify({
+                        error: `MultiEdit: edit[${i}].old_string must be non-empty`,
+                    });
+                }
+                if (rec.old_string === rec.new_string) {
+                    return JSON.stringify({
+                        error: `MultiEdit: edit[${i}] is a no-op (old_string === new_string)`,
+                    });
+                }
+                edits.push({
+                    old_string: rec.old_string,
+                    new_string: rec.new_string,
+                    replace_all: Boolean(rec.replace_all),
+                });
+            }
+            if (!existsSync(filePath)) {
+                return JSON.stringify({
+                    error: `MultiEdit: file does not exist: ${filePath}. Use Write to create new files.`,
+                });
+            }
+            let stat;
+            try {
+                stat = statSync(filePath);
+            }
+            catch (e) {
+                return JSON.stringify({
+                    error: `MultiEdit: stat failed: ${e instanceof Error ? e.message : String(e)}`,
+                });
+            }
+            if (stat.isDirectory()) {
+                return JSON.stringify({
+                    error: `MultiEdit: '${filePath}' is a directory, not a file.`,
+                });
+            }
+            if (stat.size > MAX_FILE_BYTES) {
+                return JSON.stringify({
+                    error: `MultiEdit: file size ${stat.size} exceeds 10MB cap. Use bash sed/awk for large files.`,
+                });
+            }
+            let raw;
+            try {
+                raw = readFileSync(filePath, "utf-8");
+            }
+            catch (e) {
+                return JSON.stringify({
+                    error: `MultiEdit: read failed: ${e instanceof Error ? e.message : String(e)}`,
+                });
+            }
+            // Apply edits sequentially to an in-memory buffer. Each edit sees the
+            // state left by the previous one. Any failure aborts the whole batch —
+            // the file on disk is untouched and we return `failedAt: <index>` so
+            // the model can pinpoint where the cascade broke.
+            let buffer = raw;
+            let totalReplacements = 0;
+            let firstEditNewString = null;
+            for (let i = 0; i < edits.length; i++) {
+                const { old_string, new_string, replace_all } = edits[i];
+                const occurrences = countOccurrences(buffer, old_string);
+                if (occurrences === 0) {
+                    return JSON.stringify({
+                        error: `MultiEdit: edit[${i}].old_string not found in current buffer ` +
+                            "(may have been consumed by an earlier edit, or never present).",
+                        failedAt: i,
+                    });
+                }
+                if (!replace_all && occurrences > 1) {
+                    return JSON.stringify({
+                        error: `MultiEdit: edit[${i}].old_string appears ${occurrences} times. ` +
+                            "Enlarge old_string for uniqueness, or set replace_all=true on this edit.",
+                        failedAt: i,
+                        occurrences,
+                    });
+                }
+                if (replace_all) {
+                    buffer = buffer.split(old_string).join(new_string);
+                    totalReplacements += occurrences;
+                }
+                else {
+                    const idx = buffer.indexOf(old_string);
+                    buffer = buffer.slice(0, idx) + new_string + buffer.slice(idx + old_string.length);
+                    totalReplacements += 1;
+                }
+                if (firstEditNewString === null && new_string.length > 0) {
+                    firstEditNewString = new_string;
+                }
+            }
+            try {
+                writeFileSync(filePath, buffer, "utf-8");
+            }
+            catch (e) {
+                return JSON.stringify({
+                    error: `MultiEdit: write failed: ${e instanceof Error ? e.message : String(e)}`,
+                });
+            }
+            tracker?.forget(filePath);
+            const preview = firstEditNewString
+                ? buildPreview(buffer, firstEditNewString)
+                : "[change preview unavailable]";
+            const editCount = edits.length;
+            return [
+                `File edited: ${filePath} (${editCount} edit${editCount === 1 ? "" : "s"}, ` +
+                    `${totalReplacements} total replacement${totalReplacements === 1 ? "" : "s"})`,
+                "",
+                preview,
+            ].join("\n");
+        },
+    };
+}
+/** Backwards-compatible singleton (no tracker — Read-before-Edit gate off). */
+export const multiEditTool = createMultiEditTool();
+/**
+ * Build a line-numbered preview of the buffer around the first occurrence
+ * of `marker`. Same shape as Edit's post-edit preview so the model's
+ * verification habit transfers.
+ */
+function buildPreview(buffer, marker) {
+    const idx = buffer.indexOf(marker);
+    if (idx < 0)
+        return "";
+    const allLines = buffer.split("\n");
+    let acc = 0;
+    let changedLine = 0;
+    for (let i = 0; i < allLines.length; i++) {
+        const next = acc + allLines[i].length + 1; // +1 for the dropped \n
+        if (next > idx) {
+            changedLine = i;
+            break;
+        }
+        acc = next;
+    }
+    const start = Math.max(0, changedLine - PREVIEW_LINES_AROUND);
+    const end = Math.min(allLines.length, changedLine + PREVIEW_LINES_AROUND + 1);
+    return allLines
+        .slice(start, end)
+        .map((line, i) => `${String(start + i + 1).padStart(6, " ")}\t${line}`)
+        .join("\n");
+}
+// Internal exports for tests.
+export const __MAX_FILE_BYTES = MAX_FILE_BYTES;
+export const __MAX_EDITS = MAX_EDITS;
+//# sourceMappingURL=multi_edit.js.map

package/dist/tools/builtin/multi_edit.js.map

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

package/dist/tools/builtin/web_fetch.d.ts

@@ -5,6 +5,22 @@ export declare const webFetchTool: ToolHandler;
  *  decoding and comment removal built into cheerio's .text(). Collapses
  *  whitespace and preserves paragraph breaks — clean prose, no markup noise. */
 export declare function htmlToText(html: string): string;
+/**
+ * Convert HTML to markdown using cheerio. Walks the DOM emitting markdown
+ * for the structural elements the model uses for navigation and citation
+ * (headings, links, lists, code, emphasis, blockquotes, tables).
+ *
+ * Unknown / unhandled tags fall through to their text content, so any tag
+ * we forget still contributes the inner text rather than vanishing. This
+ * is the same defensive-default claude-SDK's WebFetch markdown converter
+ * adopts.
+ *
+ * Why this lives next to `htmlToText`: hosts may want plain text for
+ * downstream NLP (still exported), but the model gets a much better
+ * picture from markdown — headings preserve outline, link anchors stay
+ * resolvable, and code blocks aren't flattened into prose.
+ */
+export declare function htmlToMarkdown(html: string): string;
 export declare const __FETCH_TIMEOUT_MS = 30000;
 export declare const __MAX_RESPONSE_BYTES: number;
 //# sourceMappingURL=web_fetch.d.ts.map

package/dist/tools/builtin/web_fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web_fetch.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/web_fetch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA4BpD,eAAO,MAAM,YAAY,EAAE,WAuG1B,CAAC;AAWF;;;gFAGgF;AAChF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAa/C;AAGD,eAAO,MAAM,kBAAkB,QAAmB,CAAC;AACnD,eAAO,MAAM,oBAAoB,QAAqB,CAAC"}
+{"version":3,"file":"web_fetch.d.ts","sourceRoot":"","sources":["../../../src/tools/builtin/web_fetch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA4BpD,eAAO,MAAM,YAAY,EAAE,WA8G1B,CAAC;AAWF;;;gFAGgF;AAChF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAa/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmBnD;AAoKD,eAAO,MAAM,kBAAkB,QAAmB,CAAC;AACnD,eAAO,MAAM,oBAAoB,QAAqB,CAAC"}