mindweave 0.0.1 → 2.1.2

package/dist/tools/chassisMux.js.map

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

package/dist/tools/checkpoints.js

@@ -0,0 +1,328 @@
+/**
+ * checkpoints.ts — a per-turn undo net for file edits.
+ *
+ * Recoverability without git: whenever a mutating tool is about to change a file,
+ * it first hands the file's ORIGINAL bytes here (once per file per turn — the
+ * first touch wins, so we keep the true pre-turn state) along with the bytes it is
+ * ABOUT TO WRITE (last write wins — that is the state we expect to find on disk).
+ * At the end of a turn the engine `seal`s those into one restorable checkpoint.
+ * `/undo` then rolls the last turn's file changes back.
+ *
+ * It's deliberately a shadow-copy in memory (bounded stack), not a shadow git
+ * repo: cheap, dependency-free, and it works even when the project isn't a git
+ * repo at all. Client-side state (holds file bytes), like the background shells —
+ * absent in bare contexts, in which case edits simply aren't checkpointed.
+ *
+ * FOUR RULES THIS FILE EXISTS TO KEEP, all learned the hard way:
+ *
+ * 1. **Never destroy work we did not do.** If a file no longer matches what we
+ *    wrote, somebody else changed it — the user, their editor, another process.
+ *    Restoring would silently overwrite that. We report it and leave it alone.
+ * 2. **A failed restore must stay retryable, but not forever.** The checkpoint is
+ *    retired once every file settles — or once retrying stops being useful. Popping
+ *    first and restoring after loses the checkpoint to one locked file; never
+ *    retiring pins that checkpoint at the top and walls off every older turn.
+ * 3. **Never say more than we did.** Anything `run_command` changed is invisible
+ *    here, and a file too large to hold is not covered either. Both are reported
+ *    rather than quietly folded into "the turn was undone".
+ * 4. **Bounded in bytes, not just in turns.** Twenty checkpoints of large files is
+ *    hundreds of megabytes resident. The count bound never was the real limit.
+ */
+import { promises as fs } from "node:fs";
+import { writeFileAtomic } from "./atomicWrite.js";
+/**
+ * Per-file ceiling on what we will hold. We keep two copies of every checkpointed
+ * file (the original, to restore; what we wrote, to detect someone else's edit), so
+ * the real cost is double. A source file past this size is not something anyone is
+ * hand-editing, and holding it would crowd out every ordinary file behind it.
+ */
+const MAX_FILE_BYTES = 4 * 1024 * 1024;
+/**
+ * Ceiling across the whole stack. Oldest checkpoints are evicted first when a new
+ * one pushes past it — except that the most recent checkpoint is always kept, even
+ * if it alone exceeds the budget. Undoing the last turn is the case that matters;
+ * leaving a user with no undo at all to satisfy a memory bound is the wrong trade.
+ */
+const MAX_TOTAL_BYTES = 32 * 1024 * 1024;
+/**
+ * How many times `/undo` re-tries a checkpoint that had files it could not write.
+ *
+ * Keeping a failed file for a retry is right — a lock from an editor or a dev server
+ * usually clears. Keeping it FOREVER is not: a file that never becomes writable would
+ * pin its checkpoint at the top of the stack permanently, and every older turn behind
+ * it would be unreachable. So retry, then give up and let the user get on.
+ */
+const MAX_UNDO_ATTEMPTS = 2;
+const byteLen = (s) => (s === null ? 0 : Buffer.byteLength(s, "utf8"));
+/**
+ * The whole undo decision, as a pure function of what we recorded and what is on
+ * disk. Split out because this is where the judgement lives — the caller does only
+ * I/O around it, and the two failure modes that matter (clobbering someone else's
+ * edit, and mishandling a file that vanished) are decided here where they can be
+ * tested exhaustively.
+ *
+ * `currentBytes` is null when the file is not on disk, for any reason.
+ */
+export function undoAction(state, currentBytes) {
+    if (state.original === null && currentBytes === null)
+        return "settled";
+    if (currentBytes !== state.written)
+        return "conflict";
+    return state.original === null ? "delete" : "restore";
+}
+/**
+ * Parse what follows `/undo`: nothing (roll back the last turn), `list` (show what
+ * is available), or a count (roll back that many turns, newest first).
+ */
+export function parseUndoArg(arg) {
+    const text = arg.trim().toLowerCase();
+    if (text === "")
+        return { kind: "undo", count: 1 };
+    if (text === "list" || text === "ls")
+        return { kind: "list" };
+    if (/^\d+$/.test(text)) {
+        const count = Number(text);
+        if (count < 1)
+            return { kind: "error", message: "How many turns? /undo 1 rolls back the last one." };
+        return { kind: "undo", count };
+    }
+    return { kind: "error", message: `I don't understand "${arg.trim()}". Use /undo, /undo list, or /undo <number>.` };
+}
+/**
+ * What the MODEL is told after an undo. Pure.
+ *
+ * Without this the rollback is invisible to it: the transcript still says the edits
+ * were made, so the next turn reasons about code that is no longer on disk. The
+ * conversation is deliberately NOT rewound — only the facts are corrected, which is
+ * the smallest honest fix for the two drifting apart.
+ */
+export function undoNotice(results, display) {
+    const list = (paths) => paths.map(display).join(", ");
+    const gather = (pick) => [...new Set(results.flatMap(pick))];
+    const labels = results.map((r) => `"${r.label}"`).join(", ");
+    const lines = [
+        `The user ran /undo. The file changes from ${labels} were rolled back on disk.`,
+    ];
+    const restored = gather((r) => r.restored);
+    const conflicts = gather((r) => r.conflicts);
+    const failed = gather((r) => r.failed);
+    const skipped = gather((r) => r.skipped);
+    if (restored.length > 0) {
+        lines.push(`Back to their pre-turn state: ${list(restored)}. Your edits to these are gone.`);
+    }
+    if (conflicts.length > 0) {
+        lines.push(`Left as they are, because they changed after you wrote them: ${list(conflicts)}.`);
+    }
+    if (failed.length > 0) {
+        lines.push(`Could not be rolled back and are still in their edited state: ${list(failed)}.`);
+    }
+    if (skipped.length > 0) {
+        lines.push(`Too large to checkpoint, so still in their edited state: ${list(skipped)}.`);
+    }
+    if (results.some((r) => r.ranShell)) {
+        lines.push("Shell commands also ran; whatever those changed was not rolled back.");
+    }
+    lines.push("Re-read any of these before editing them again.");
+    return lines.join(" ");
+}
+export class Checkpoints {
+    max;
+    current = new Map();
+    currentBytes = 0;
+    currentSkipped = new Set();
+    shellRan = false;
+    stack = [];
+    resumed = false;
+    constructor(max = 20) {
+        this.max = max;
+    }
+    /**
+     * Record a file's pre-change content the first time it's touched this turn, and
+     * the content being written now. `original` is the exact bytes on disk (or null
+     * for a not-yet-existing file); `written` is what the tool is about to put there.
+     *
+     * A file too large to hold is recorded as SKIPPED rather than dropped silently —
+     * `/undo` then says it wasn't covered instead of implying it was.
+     */
+    backup(absPath, original, written) {
+        const prior = this.current.get(absPath);
+        if (prior) {
+            // A later touch in the same turn moves only `written`; `original` is the
+            // pre-turn truth and never changes.
+            const grown = byteLen(original) + byteLen(written);
+            if (grown > MAX_FILE_BYTES) {
+                // It has outgrown what we can hold. Drop it wholesale rather than keep a
+                // half-record we would have to reason about at restore time.
+                this.currentBytes -= byteLen(prior.original) + byteLen(prior.written);
+                this.current.delete(absPath);
+                this.currentSkipped.add(absPath);
+                return;
+            }
+            this.currentBytes += byteLen(written) - byteLen(prior.written);
+            prior.written = written;
+            return;
+        }
+        const cost = byteLen(original) + byteLen(written);
+        if (cost > MAX_FILE_BYTES || this.currentBytes + cost > MAX_TOTAL_BYTES) {
+            this.currentSkipped.add(absPath);
+            return;
+        }
+        this.current.set(absPath, { original, written });
+        this.currentBytes += cost;
+    }
+    /** Note that this turn ran a shell command, whose effects we cannot capture. */
+    noteShell() {
+        this.shellRan = true;
+    }
+    /**
+     * Mark this as a resumed session. Undo history lives in memory, so a resumed
+     * session starts empty even though earlier turns really did change files — the
+     * difference matters when telling the user why there is nothing to undo.
+     */
+    noteResumed() {
+        this.resumed = true;
+    }
+    /** Whether this session was resumed (so earlier turns' undo history is gone). */
+    wasResumed() {
+        return this.resumed;
+    }
+    /** Close this turn's edits into a restorable checkpoint. No-op if nothing happened. */
+    seal(label) {
+        // A turn whose only file changes were too large still gets a checkpoint: it has
+        // nothing to restore, but it has something to SAY, and saying it is the point.
+        if (this.current.size === 0 && this.currentSkipped.size === 0) {
+            this.shellRan = false;
+            return;
+        }
+        this.stack.push({
+            label: label || "(edits)",
+            at: Date.now(),
+            files: this.current,
+            skipped: [...this.currentSkipped],
+            ranShell: this.shellRan,
+            bytes: this.currentBytes,
+            attempts: 0,
+        });
+        this.current = new Map();
+        this.currentBytes = 0;
+        this.currentSkipped = new Set();
+        this.shellRan = false;
+        this.evict();
+    }
+    /** Trim the stack to both bounds: the turn count, then the byte budget. */
+    evict() {
+        while (this.stack.length > this.max)
+            this.stack.shift();
+        let total = this.stack.reduce((n, cp) => n + cp.bytes, 0);
+        // `length > 1` keeps the newest checkpoint whatever it costs — see MAX_TOTAL_BYTES.
+        // Currently unreachable, because `backup` already refuses once a single turn's
+        // held bytes would pass the budget, so no lone checkpoint can exceed it. Kept
+        // anyway: it is one condition, and it is what stops that in-turn cap from
+        // becoming load-bearing in a way nobody would notice if it were relaxed.
+        while (total > MAX_TOTAL_BYTES && this.stack.length > 1) {
+            total -= this.stack.shift().bytes;
+        }
+    }
+    /** Whether there's a sealed checkpoint to undo. */
+    hasUndo() {
+        return this.stack.length > 0;
+    }
+    /** The label of the checkpoint that `undo()` would restore, if any. */
+    nextUndoLabel() {
+        return this.stack[this.stack.length - 1]?.label;
+    }
+    /** What is available to undo, newest first. */
+    list() {
+        return [...this.stack]
+            .reverse()
+            .map((cp) => ({
+            label: cp.label,
+            at: cp.at,
+            files: cp.files.size,
+            skipped: cp.skipped.length,
+            ranShell: cp.ranShell,
+        }));
+    }
+    /**
+     * Restore the most recent sealed checkpoint. Files that no longer match what we
+     * wrote are reported as conflicts and left untouched; files that fail to write
+     * are reported and KEPT in the checkpoint so a second `/undo` retries just those.
+     * The checkpoint retires when nothing is left in it, or when retrying it has
+     * stopped being useful.
+     */
+    async undo() {
+        const cp = this.stack[this.stack.length - 1];
+        if (!cp)
+            return null;
+        const restored = [];
+        const conflicts = [];
+        const failed = [];
+        for (const [path, state] of [...cp.files]) {
+            let currentBytes;
+            try {
+                currentBytes = await fs.readFile(path, "utf8");
+            }
+            catch {
+                currentBytes = null; // not on disk (deleted, or never created)
+            }
+            const action = undoAction(state, currentBytes);
+            if (action === "settled") {
+                cp.files.delete(path); // nothing to do, nothing worth reporting
+                continue;
+            }
+            if (action === "conflict") {
+                conflicts.push(path);
+                cp.files.delete(path); // reported once; their copy stands
+                continue;
+            }
+            try {
+                if (action === "delete")
+                    await fs.rm(path, { force: true });
+                // ATOMIC, like every other write to a user's file. Writing straight onto the
+                // destination truncates it first, so a crash inside that window destroys the
+                // file — during the one operation whose entire purpose is to save it. Undo is
+                // the recovery mechanism; it must not be the thing that loses the work.
+                else
+                    await writeFileAtomic(path, state.original);
+                restored.push(path);
+                cp.files.delete(path);
+            }
+            catch {
+                failed.push(path); // left in place so the next /undo can try again
+            }
+        }
+        cp.attempts++;
+        const retired = cp.files.size === 0 || cp.attempts >= MAX_UNDO_ATTEMPTS;
+        if (retired)
+            this.stack.pop();
+        return {
+            label: cp.label,
+            at: cp.at,
+            restored,
+            conflicts,
+            failed,
+            retryable: failed.length > 0 && !retired,
+            skipped: cp.skipped,
+            ranShell: cp.ranShell,
+        };
+    }
+    /**
+     * Undo up to `count` checkpoints, newest first — the coherent way to go back more
+     * than one turn, since a later turn's edits sit on top of an earlier one's. Stops
+     * early if the stack runs out, or if a checkpoint is left retryable (pressing on
+     * past a file we could not write would unwind state the user thinks is still here).
+     */
+    async undoMany(count) {
+        const results = [];
+        for (let i = 0; i < count; i++) {
+            const result = await this.undo();
+            if (!result)
+                break;
+            results.push(result);
+            if (result.retryable)
+                break;
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=checkpoints.js.map

package/dist/tools/checkpoints.js.map

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

package/dist/tools/codeIntel.js

@@ -0,0 +1,267 @@
+/**
+ * codeIntel.ts — the read-only tools that query the chassis (Mindweave's code map).
+ *
+ * These give the model IDE-grade navigation — outline, jump-to-definition,
+ * find-references, and a relevance map — without reading or grepping blindly.
+ * They query `ctx.chassis` (built by the alternator lane) and fall back to a
+ * clear "use grep/read" message when it isn't available. Every result carries
+ * the chassis's confidence: `name-level` answers tell the model to verify with
+ * grep when exact identity matters (the assistant-not-authority rule).
+ */
+import { promises as fs } from "node:fs";
+import { relativize, resolvePath } from "./paths.js";
+import { allChassis, chassisForPath, mergedDefinition, mergedReferences } from "./chassisMux.js";
+import { walkFiles } from "./walk.js";
+import { excludedFromSearch } from "./guard.js";
+import { isSupported } from "../alternator/chassis/treesitter.js";
+import { isMarkupSupported } from "../alternator/chassis/markup.js";
+import { fail, failQuietly } from "./results.js";
+const DIR_FILE_CAP = 40;
+const REF_CAP = 100;
+function indexingNote(ctx) {
+    return ctx.chassis?.status().ready ? "" : " (code map still indexing — may be incomplete)";
+}
+function caveat(confidence) {
+    return confidence === "name-level"
+        ? "\n(name-level match — verify with grep if exact identity matters)"
+        : "";
+}
+const outlineDef = {
+    name: "outline",
+    readOnly: true,
+    // Two things were missing, and the second one matters more than it looks. A directory
+    // outline leads with a rollup (counts, the central symbols, which folders it depends
+    // on) that the description never mentioned, so the model had no reason to point this
+    // at a folder. And a directory outline stops after DIR_FILE_CAP files WITHOUT saying
+    // so, which means a model that outlines a 200-file folder believes it has seen the
+    // shape of all of it. Silent truncation is the worst kind: it looks like completeness.
+    description: "Show the structural outline of a file: its symbols and signatures, never bodies. " +
+        "Point it at a DIRECTORY and you get more than the files, you get a rollup first — " +
+        "how many files and symbols it holds, which symbols are most central to it, and " +
+        "which other folders it depends on. That is the fastest way to understand an " +
+        "unfamiliar area, and it costs one call. " +
+        `A directory outline covers at most ${DIR_FILE_CAP} files, so for anything larger ` +
+        "treat it as a sample and narrow to a subfolder. Files with no symbols are left out. " +
+        "Works on HTML and CSS too: it lists a page's sections and ids, and a stylesheet's " +
+        "selectors, with line numbers, so you can navigate a big page instead of reading it " +
+        "top to bottom.",
+    parameters: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            path: { type: "string", description: "File or directory. Defaults to the working directory." },
+        },
+    },
+    async execute(args, ctx) {
+        if (allChassis(ctx).length === 0)
+            return degraded();
+        const rawPath = typeof args.path === "string" && args.path.trim() ? args.path.trim() : ".";
+        const abs = resolvePath(ctx, rawPath);
+        let stat;
+        try {
+            stat = await fs.stat(abs);
+        }
+        catch {
+            return fail(`path not found: ${rawPath}`);
+        }
+        const groups = [];
+        let rollup = "";
+        let dirTruncated = null;
+        if (stat.isFile()) {
+            const entries = await (chassisForPath(ctx, abs)?.outline(abs) ?? Promise.resolve([]));
+            groups.push({ file: abs, entries });
+        }
+        else {
+            // A directory: lead with a folder rollup (counts, central symbols, deps).
+            const summary = await chassisForPath(ctx, abs)?.directorySummary(abs);
+            if (summary)
+                rollup = renderDirSummary(ctx, summary);
+            const { files } = await walkFiles(abs, 5000);
+            // `excludedFromSearch` is what keeps secrets and other agents' data out of
+            // grep and glob. outline walked the same tree without it, so the one
+            // discovery tool that reads file CONTENTS to build its output was the one not
+            // applying the exclusion. Same list, same walk, same rule.
+            const eligible = files.filter((f) => !excludedFromSearch(f.abs) && (isSupported(f.abs) || isMarkupSupported(f.abs)));
+            const supported = eligible.slice(0, DIR_FILE_CAP);
+            // Say so when the cap bites. The description warns that a cap exists, but a
+            // model reading one particular reply cannot tell whether THIS answer hit it,
+            // and truncation that looks like completeness is how a partial survey gets
+            // treated as the shape of the whole folder.
+            if (eligible.length > supported.length) {
+                dirTruncated = { shown: supported.length, total: eligible.length };
+            }
+            for (const f of supported) {
+                const entries = (await chassisForPath(ctx, f.abs)?.outline(f.abs)) ?? [];
+                if (entries.length)
+                    groups.push({ file: f.abs, entries });
+            }
+        }
+        const outlineBody = groups
+            .map((g) => {
+            const header = relativize(ctx, g.file);
+            return `${header}\n${renderOutlineEntries(g.entries).join("\n")}`;
+        })
+            .join("\n\n");
+        const truncNote = dirTruncated
+            ? `\n\n(outlined ${dirTruncated.shown} of ${dirTruncated.total} files — this is a ` +
+                `sample, not the whole folder; narrow to a subfolder to see the rest)`
+            : "";
+        const body = [rollup, outlineBody].filter(Boolean).join("\n\n");
+        if (!body)
+            return { output: `No symbols found in ${rawPath}.${indexingNote(ctx)}`, summary: `outline ${rawPath} (empty)` };
+        return {
+            output: body + truncNote + indexingNote(ctx),
+            summary: `outline ${rawPath} (${groups.length} file${groups.length === 1 ? "" : "s"})`,
+        };
+    },
+};
+const definitionDef = {
+    name: "definition",
+    readOnly: true,
+    // "the exact file:line" was an overclaim: a name defined in two files returns BOTH,
+    // which is the right behaviour and needs saying, because a model told it gets THE
+    // location will take the first row. The genuinely useful part was also unstated:
+    // the declaration line comes back with the location, so most lookups need no read
+    // at all. Same two-level certainty as references, for the same reason.
+    description: "Find where a symbol (function, class, type, and so on) is defined, by name. " +
+        "Returns file:line PLUS the declaration itself, so for most lookups you never need " +
+        "to open the file; use read_symbol when you want the body. " +
+        "If the name is defined in more than one place you get EVERY definition rather than " +
+        "a best guess, so an ambiguous name is visible instead of silently resolved. " +
+        "Certainty comes in two levels and the output says which one you got: resolved when " +
+        "a language server has analyzed the file, otherwise a NAME match, which can include " +
+        "an unrelated symbol that happens to share the name. " +
+        "Covers HTML and CSS as well: pass a CSS class or id (e.g. \"hero-stats\") to jump " +
+        "to its style rule, or an element id to find that section. " +
+        "An empty result means it is not in the code map, which may still be indexing, so " +
+        "fall back to grep rather than concluding the symbol does not exist.",
+    parameters: {
+        type: "object",
+        additionalProperties: false,
+        required: ["name"],
+        properties: { name: { type: "string", description: "The symbol name to locate." } },
+    },
+    async execute(args, ctx) {
+        if (allChassis(ctx).length === 0)
+            return degraded();
+        const name = typeof args.name === "string" ? args.name.trim() : "";
+        if (!name)
+            return failQuietly("`name` is required.");
+        const { symbols, confidence } = await mergedDefinition(ctx, name);
+        if (symbols.length === 0) {
+            return { output: `No definition of '${name}' in the code map.${indexingNote(ctx)} Try grep.`, summary: `definition ${name} — none` };
+        }
+        const body = symbols
+            .map((s) => `${relativize(ctx, s.file)}:${s.line}  ${s.kind} ${s.signature ?? s.name}`)
+            .join("\n");
+        return { output: body + caveat(confidence) + indexingNote(ctx), summary: `definition ${name} (${symbols.length})` };
+    },
+};
+const referencesDef = {
+    name: "references",
+    readOnly: true,
+    // The old description read as if this were full semantic resolution. It is not, and
+    // the difference decides whether the model can trust the list: refs are keyed by NAME
+    // in the graph, and only files a language server has analyzed come back `resolved`.
+    // The tool already prints that caveat at runtime; a model that has not been told the
+    // distinction up front reads a name-level list as certainty and refactors on it.
+    description: "Find where a symbol is used, by name. Reads PARSED code rather than raw text, so a " +
+        "mention inside a comment or a string is never a match. Returns file:line locations " +
+        `(up to ${REF_CAP}), not the code itself. ` +
+        "There are TWO levels of certainty here and the output tells you which one you got. " +
+        "When a language server has analyzed the files involved, the answer is resolved. " +
+        "Otherwise it is a NAME match, and a different symbol that happens to share the name " +
+        "in an unrelated file WILL appear in the list. When it says name-level and exact " +
+        "identity matters, confirm with grep or by opening the candidates before you act. " +
+        "For a CSS class or id this returns every HTML element and every script " +
+        "(getElementById/querySelector/classList) that uses it, which is the cross-language " +
+        "blast radius before you change a style. " +
+        "An empty result means nothing in the code map references it; the map may still be " +
+        "indexing, so fall back to grep rather than concluding the symbol is unused.",
+    parameters: {
+        type: "object",
+        additionalProperties: false,
+        required: ["name"],
+        properties: { name: { type: "string", description: "The symbol name to find references to." } },
+    },
+    async execute(args, ctx) {
+        if (allChassis(ctx).length === 0)
+            return degraded();
+        const name = typeof args.name === "string" ? args.name.trim() : "";
+        if (!name)
+            return failQuietly("`name` is required.");
+        const { refs, confidence } = await mergedReferences(ctx, name);
+        if (refs.length === 0) {
+            return { output: `No references to '${name}' in the code map.${indexingNote(ctx)} Try grep.`, summary: `references ${name} — none` };
+        }
+        const shown = refs.slice(0, REF_CAP).map((r) => `${relativize(ctx, r.file)}:${r.line}`);
+        if (refs.length > REF_CAP)
+            shown.push(`… (${refs.length - REF_CAP} more)`);
+        return { output: shown.join("\n") + caveat(confidence) + indexingNote(ctx), summary: `references ${name} (${refs.length})` };
+    },
+};
+/** Render a directory rollup: counts, its most central symbols, and folder deps. */
+function renderDirSummary(ctx, s) {
+    const where = relativize(ctx, s.dir);
+    const lines = [`${where}/ — ${s.files} file${s.files === 1 ? "" : "s"}, ${s.symbols} symbol${s.symbols === 1 ? "" : "s"}`];
+    if (s.topSymbols.length) {
+        lines.push(`  central: ${s.topSymbols.slice(0, 8).map((sym) => `${sym.name} (${sym.kind})`).join(", ")}`);
+    }
+    if (s.dependsOn.length) {
+        lines.push(`  depends on: ${s.dependsOn.map((d) => `${relativize(ctx, d)}/`).join(", ")}`);
+    }
+    return lines.join("\n");
+}
+/** Render a nested outline: indent by depth, show each symbol's doc when present. */
+export function renderOutlineEntries(entries, depth = 0) {
+    const out = [];
+    for (const e of entries) {
+        const indent = "  ".repeat(depth);
+        const doc = e.doc ? `  — ${e.doc}` : "";
+        out.push(`  ${String(e.line).padStart(4)}  ${indent}${e.kind} ${e.name}${doc}`);
+        if (e.children?.length)
+            out.push(...renderOutlineEntries(e.children, depth + 1));
+    }
+    return out;
+}
+function degraded() {
+    return {
+        output: "The code map isn't available here — use grep, glob, and read_file instead.",
+        summary: "code map unavailable",
+    };
+}
+/**
+ * These four never render a row.
+ *
+ * Outlining a file, resolving a definition, finding call sites, ranking what's
+ * relevant — that is the agent reading its way around the code, not work done
+ * TO the project. A row per lookup filled the transcript with the agent's own
+ * navigation while saying nothing the user could act on; the answers show up in
+ * what it goes on to say and do. The model still receives every result in full.
+ *
+ * Applied as a wrapper rather than a `quiet: true` on each return, because these
+ * four tools have eleven return sites between them and the next one added would
+ * silently start rendering again.
+ */
+function navigational(tool) {
+    return {
+        ...tool,
+        /**
+         * Deferred, all four of them. They answer structural questions — where is this
+         * defined, what calls it, what is related — which is a phase of a task rather than a
+         * step in the edit loop, and four schemas is 1,257 tokens in front of the model on
+         * every single request.
+         *
+         * Marked here rather than on each definition because it is one decision about one
+         * family; splitting it four ways is four places for it to drift.
+         */
+        deferred: true,
+        async execute(args, ctx) {
+            return { ...(await tool.execute(args, ctx)), quiet: true };
+        },
+    };
+}
+export const outlineTool = navigational(outlineDef);
+export const definitionTool = navigational(definitionDef);
+export const referencesTool = navigational(referencesDef);
+//# sourceMappingURL=codeIntel.js.map

package/dist/tools/codeIntel.js.map

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