mindweave 0.0.1 → 2.1.2

package/dist/tools/readFile.js

@@ -0,0 +1,371 @@
+/**
+ * readFile.ts — Mindweave's first tool: read a text file.
+ *
+ * The smallest useful, fully read-only capability — it proves the whole
+ * tool loop end-to-end without any risk of changing the user's files.
+ *
+ * Design borrows the proven essentials from mature agents (line-numbered
+ * output, optional offset/limit range, a size cap that nudges toward ranged
+ * reads, binary refusal, a friendly not-found). It deliberately does NOT carry
+ * "read surgically / how to investigate" guidance — that is the model's
+ * judgment, not the tool's job.
+ */
+import { promises as fs } from "node:fs";
+import { foreignAgentReason, protectedPathReason } from "./guard.js";
+import { requestAgentDataAccess } from "./approval.js";
+import { relativize, resolvePath, nextTouch, touch, markScope } from "./paths.js";
+import { addFocus } from "./focus.js";
+import { chassisForPath } from "./chassisMux.js";
+import { renderOutlineEntries } from "./codeIntel.js";
+import { estimateTokens } from "../memory/compaction.js";
+import { failQuietly } from "./results.js";
+// Caps protect the model's context window, not the disk. They are deliberately
+// MODEL-AGNOSTIC fixed defaults, not derived from any one model's context window —
+// so they stay correct as other models are added.
+//   - MAX_BYTES: refuse a whole-file read of a file this large; use a range.
+//   - MAX_LINES: a default read returns at most this many lines (the model pages
+//     with offset for more). This is the big BYOK-cost lever — a 5000-line file
+//     costs one bounded read, not 5000 lines every time.
+//   - MAX_OUTPUT_CHARS: final safety truncation (e.g. minified long lines).
+const MAX_BYTES = 256 * 1024;
+const MAX_LINES = envInt("MINDWEAVE_READ_MAX_LINES", 2000);
+const MAX_OUTPUT_CHARS = 120_000;
+/**
+ * Most files one call may read.
+ *
+ * The point of the list is to collapse round trips, not to let a single call pull an
+ * unbounded amount of the repository into context. Ten covers every batch a real task
+ * asks for; past that the model should be searching, not reading.
+ */
+const MAX_FILES = 10;
+/**
+ * Token budget for a WHOLE-file read, past which the file's structure is returned
+ * instead of its contents.
+ *
+ * The habit this exists to break: answering "where is this handled?" by reading a
+ * 1,700-line file. That costs its full length on the request that fetches it AND on
+ * every request afterwards for the rest of the turn, so one careless read is re-billed
+ * five or ten times. The usual answer is a hard token cap that refuses the read; this
+ * one does better, because the code map already knows the file's shape.
+ *
+ * ~8,000 tokens is roughly 700 lines of code. Below that a whole read is a reasonable
+ * way to understand a file. Above it, the model almost never wants all of it — it wants
+ * one function — and an outline plus a ranged follow-up costs a fraction of the same
+ * answer. A range is NEVER budgeted: asking for specific lines is already the careful
+ * behaviour, and second-guessing it would just cost a round trip.
+ */
+const WHOLE_READ_TOKEN_BUDGET = envInt("MINDWEAVE_WHOLE_READ_TOKENS", 8_000);
+// Returned instead of re-sending identical content when a file is unchanged
+// since the model last read it — pure token savings on a re-read.
+const FILE_UNCHANGED = "This file is unchanged since you last read it in this conversation — the " +
+    "earlier read is still current, use that instead of re-reading.";
+export const readFile = {
+    name: "read_file",
+    readOnly: true,
+    // The description states the tool's CONTRACT, not just its happy path, because two
+    // of its outcomes are easy to misread as failures and one of its roles is invisible
+    // from here. Every claim below is checked against the behaviour in `execute`; if that
+    // changes, this changes with it.
+    description: `Read text files and return their contents with line numbers. ` +
+        `\`paths\` TAKES A LIST: pass every file you want in ONE call rather than calling ` +
+        `this once per file. Each extra call is a full model round-trip that re-sends the ` +
+        `whole conversation, so four separate reads cost several times what one read of ` +
+        `four files costs, and take four times as long. Up to ${MAX_FILES} at a time. ` +
+        `When you already know which part of a file you need, READ ONLY THAT PART: pass ` +
+        `\`offset\` (and optionally \`limit\`). A range applies to a SINGLE file: pass one path ` +
+        `when you use one, or the range is ignored and the files come back whole. ` +
+        `Reading a file whole costs its full length on this ` +
+        `request and on every later one this turn, so a needless whole read is paid for many ` +
+        `times over. ` +
+        `A whole read past ~${Math.round(WHOLE_READ_TOKEN_BUDGET / 1000)}k tokens returns the ` +
+        `file's STRUCTURE — its symbols with line numbers — instead of its contents, so you ` +
+        `can follow up with the exact range, or with read_symbol for one symbol by name. ` +
+        `That is an answer, not a failure. ` +
+        `Otherwise reads up to ${MAX_LINES} lines per file from the start. A file larger than ` +
+        `${Math.round(MAX_BYTES / 1024)} KB must be read with \`limit\` set rather than whole. ` +
+        `Very long output is truncated at the end, and says so. ` +
+        `One unreadable path does not fail the others: it is reported in place and the rest ` +
+        `still come back. ` +
+        `Reading is also what unlocks editing: edit, replace_symbol_body ` +
+        `and overwriting an existing file with write_file all require that file to have ` +
+        `been read this session (read_symbol counts too). ` +
+        `ONE REPLY MEANS YOU ALREADY HAVE THE FILE and should not read it again: it says the ` +
+        `file is unchanged since your earlier read in this conversation, so that earlier read ` +
+        `is still current. It is a successful read, and it satisfies the edit requirement above. ` +
+        `When you only want one function, class or type, prefer read_symbol, which returns ` +
+        `just that symbol instead of pulling in a large file to look at a small part of it.`,
+    parameters: {
+        type: "object",
+        additionalProperties: false,
+        required: ["paths"],
+        properties: {
+            paths: {
+                type: "array",
+                minItems: 1,
+                maxItems: MAX_FILES,
+                items: { type: "string" },
+                description: "The files to read, absolute or relative to the working directory. Pass every " +
+                    "file you need at once — one call with four paths costs a quarter of what four " +
+                    "calls cost.",
+            },
+            offset: {
+                type: "integer",
+                minimum: 1,
+                description: "1-based line number to start at. Ignored unless `paths` holds exactly one file.",
+            },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                description: "Number of lines to read from `offset`. Ignored unless `paths` holds exactly one file.",
+            },
+        },
+    },
+    async execute(args, ctx) {
+        const paths = toPathList(args);
+        if (paths.length === 0)
+            return failQuietly("`paths` is required — pass at least one file.");
+        if (paths.length > MAX_FILES) {
+            return failQuietly(`Too many files (${paths.length}). Read at most ${MAX_FILES} in one call.`);
+        }
+        let offset = toPositiveInt(args.offset);
+        let limit = toPositiveInt(args.limit);
+        // A range names lines in ONE file. Applying it across a list would silently return a
+        // different slice of each, which reads as an answer and is not one — so the range is
+        // DROPPED here rather than honoured.
+        //
+        // It is dropped, though, and not treated as a failed call. Rejecting the whole call
+        // costs a round trip to recover, which is the exact cost this tool exists to avoid —
+        // the same reason one unreadable path below does not fail the others. In practice it
+        // cost more than the round trip: told only to pass a single path, a model retried
+        // with the first path and silently abandoned the rest of its list.
+        //
+        // Whole reads are already bounded by WHOLE_READ_TOKEN_BUDGET, so dropping a range
+        // cannot turn a cheap ranged read into an unbounded one.
+        const rangeDropped = (offset !== undefined || limit !== undefined) && paths.length > 1;
+        if (rangeDropped) {
+            offset = undefined;
+            limit = undefined;
+        }
+        const parts = [];
+        const summaries = [];
+        const fullPaths = [];
+        let failures = 0;
+        for (const rawPath of paths) {
+            const one = await readOne(rawPath, ctx, offset, limit);
+            // A bad path is reported IN PLACE rather than failing the call. Losing three good
+            // reads because the fourth was misspelled would cost another whole round trip to
+            // recover, which is the exact cost this tool exists to avoid.
+            if (one.error)
+                failures++;
+            parts.push(paths.length > 1 ? `===== ${one.label} =====\n${one.body}` : one.body);
+            summaries.push(one.summary);
+            if (one.fullPath)
+                fullPaths.push(one.fullPath);
+        }
+        if (paths.length === 1) {
+            return {
+                output: parts.join("\n"),
+                summary: summaries[0] ?? "",
+                ...(failures > 0 ? { isError: true } : {}),
+                ...(fullPaths.length > 0 ? { fullContentOf: fullPaths } : {}),
+            };
+        }
+        // Prepended as another part rather than raised as an error, so the model learns the
+        // rule and still gets every file it asked for.
+        if (rangeDropped) {
+            parts.unshift("Note: `offset`/`limit` name lines in a single file, so the range was ignored and " +
+                `all ${paths.length} files were read whole. To read a range, call again with one path.`);
+        }
+        return {
+            output: parts.join("\n\n"),
+            summary: `read ${paths.length} files${failures > 0 ? ` (${failures} failed)` : ""}`,
+            ...(fullPaths.length > 0 ? { fullContentOf: fullPaths } : {}),
+        };
+    },
+};
+/**
+ * Read one file. Every rule here — the caps, the dedup, the presence flag — is per file
+ * and unchanged by batching; only the number of files a single call handles is new.
+ */
+async function readOne(rawPath, ctx, offset, limit) {
+    const bad = (message) => ({
+        label: rawPath,
+        body: `Error: ${message}`,
+        summary: message,
+        error: true,
+    });
+    const trimmed = rawPath.trim();
+    if (!trimmed)
+        return bad("empty path.");
+    const filePath = resolvePath(ctx, trimmed);
+    const blocked = protectedPathReason(filePath);
+    if (blocked)
+        return bad(`Refusing to read ${trimmed}: it is ${blocked}.`);
+    const otherTool = foreignAgentReason(filePath);
+    if (otherTool) {
+        const denied = await requestAgentDataAccess(ctx, otherTool, `Reading ${trimmed}`);
+        if (denied)
+            return bad(denied.summary ?? "access refused");
+    }
+    let stat;
+    try {
+        stat = await fs.stat(filePath);
+    }
+    catch {
+        return bad(`File not found: ${trimmed}`);
+    }
+    if (stat.isDirectory())
+        return bad(`${trimmed} is a directory, not a file.`);
+    const full = offset === undefined && limit === undefined;
+    const prior = ctx.reads.get(filePath);
+    const unchanged = prior !== undefined && prior.mtimeMs === stat.mtimeMs && prior.size === stat.size;
+    // Read-dedup: if the model already read this whole file, it hasn't changed since
+    // (same mtime + size), and that earlier read is STILL IN the transcript, don't
+    // re-send the content. The presence half is derived per turn rather than read off
+    // the ledger: microcompaction can clear the earlier result's body at any time, and
+    // a stored "you have it" bit would then be a lie the model obeys. No presence set
+    // (a subagent, a test) means no dedup — a wasted read, never a phantom one.
+    if (full && prior?.full && unchanged && ctx.transcriptFull?.has(filePath)) {
+        touch(ctx, filePath);
+        const shown = relativize(ctx, filePath);
+        return { label: shown, body: FILE_UNCHANGED, summary: `read ${shown} (unchanged)` };
+    }
+    if (limit === undefined && stat.size > MAX_BYTES) {
+        return bad(`File is large (${formatBytes(stat.size)}). Read a range with \`offset\` and \`limit\` instead of the whole file.`);
+    }
+    const buf = await fs.readFile(filePath);
+    if (looksBinary(buf))
+        return bad(`${trimmed} looks like a binary file; cannot read as text.`);
+    // A WHOLE read of a big file: answer with the file's shape instead of its contents.
+    //
+    // This is the one place the code map pays for itself. The alternative on offer
+    // elsewhere is an error telling the model to "use offset and limit" — which it cannot
+    // act on, because it does not know which lines it wants yet. That is the whole reason
+    // the whole-file read happens. An outline answers the question the read was really
+    // asking ("where in here is the thing I need?") and makes the follow-up a precise
+    // range instead of another guess.
+    //
+    // Ranges are exempt by construction: this branch only runs when `full` is true.
+    if (full) {
+        const estimate = estimateTokens(buf.toString("utf8"));
+        if (estimate > WHOLE_READ_TOKEN_BUDGET) {
+            const shown = relativize(ctx, filePath);
+            const lineTotal = buf.toString("utf8").split(/\r?\n/).length;
+            const head = `${shown} is ${lineTotal} lines (~${Math.round(estimate / 100) / 10}k tokens), too large to read whole — ` +
+                `reading it would re-send all of that on every later request this turn.`;
+            const entries = (await chassisForPath(ctx, filePath)?.outline(filePath)) ?? [];
+            if (entries.length > 0) {
+                return {
+                    label: shown,
+                    body: `${head}\n\nIts structure, with line numbers:\n\n` +
+                        renderOutlineEntries(entries).join("\n") +
+                        `\n\nRead the part you need with \`offset\`/\`limit\`, or read_symbol for one symbol by name.`,
+                    summary: `outlined ${shown} (${lineTotal} lines — too large to read whole)`,
+                };
+            }
+            // No outline for this file type. Say the size and how to proceed, which is all a
+            // language the code map cannot parse allows us to say honestly.
+            return bad(`${head} Read a range with \`offset\` and \`limit\`, or search it for the part you need.`);
+        }
+    }
+    // Split on CRLF or LF so a Windows file doesn't show a trailing \r on every
+    // line — the model can't see it, would omit it from an edit's old_string, and
+    // the edit would then fail to match. The edit tool normalizes line endings too.
+    const allLines = buf.toString("utf8").split(/\r?\n/);
+    const totalLines = allLines.length;
+    const start = offset ?? 1;
+    if (start > totalLines) {
+        return bad(`offset ${start} is past the end of the file (${totalLines} lines).`);
+    }
+    // A read with no explicit limit still stops after MAX_LINES — the default
+    // read is bounded, and the model pages with offset for the rest.
+    const effectiveLimit = limit ?? MAX_LINES;
+    const end = Math.min(totalLines, start - 1 + effectiveLimit);
+    const slice = allLines.slice(start - 1, end);
+    // Line numbers, right-aligned to the widest number in the slice.
+    const width = String(end).length;
+    let body = slice.map((line, i) => `${String(start + i).padStart(width)}\t${line}`).join("\n");
+    // Tell the model when the default cap hid the rest of the file.
+    if (limit === undefined && end < totalLines) {
+        body += `\n… (showing lines ${start}-${end} of ${totalLines}; pass offset to read further)`;
+    }
+    const charTruncated = body.length > MAX_OUTPUT_CHARS;
+    if (charTruncated) {
+        body = body.slice(0, MAX_OUTPUT_CHARS) + "\n… (truncated — read a smaller range with offset/limit)";
+    }
+    // "Whole file" means the whole file ACTUALLY WENT OUT, not merely that the caller
+    // asked for no range. A 2500-line file read with no offset stops at the MAX_LINES
+    // cap, and recording that as full let a later re-read be answered "unchanged since
+    // you last read" for 500 lines the model was never shown. Same for the character
+    // cap. The flag is the dedup's whole basis, so it has to mean what it says.
+    const wholeFileSent = full && end >= totalLines && !charTruncated;
+    // Record the read so edit / write_file know this file has been seen, so a
+    // later identical read can be deduped, and so it enters the working set (recency +
+    // the focused range for a partial read, used to localize a large file).
+    markScope(ctx, filePath);
+    ctx.reads.set(filePath, {
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+        full: wholeFileSent,
+        touchedAt: nextTouch(),
+        focus: !wholeFileSent ? addFocus(prior?.focus, { start, end }) : prior?.focus,
+    });
+    const shown = relativize(ctx, filePath);
+    const ranged = offset !== undefined || limit !== undefined;
+    return {
+        label: shown,
+        body,
+        summary: ranged ? `read ${shown} lines ${start}-${end}` : `read ${shown} (${slice.length} lines)`,
+        // Presence, recorded as a FACT at the moment it is true, keyed by the absolute path
+        // this call actually resolved to. Re-deriving it later by re-resolving these
+        // arguments would be a guess: `cd` moves the working directory mid-session, so the
+        // same recorded "a.ts" can resolve to a different file than it did when read.
+        ...(wholeFileSent ? { fullPath: filePath } : {}),
+    };
+}
+/**
+ * The paths one call asked for.
+ *
+ * Accepts a bare string as well as a list, and still reads the old singular `path`,
+ * because a resumed session replays tool calls the model made under the previous schema
+ * — refusing those would turn every `/continue` into a wall of errors.
+ */
+function toPathList(args) {
+    const raw = args.paths ?? args.path;
+    if (typeof raw === "string")
+        return raw.trim() ? [raw] : [];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((v) => typeof v === "string" && v.trim().length > 0);
+}
+/** A positive integer from an env var, or `fallback`. Lets caps be tuned without
+ *  baking any one model's limits into the code. */
+function envInt(name, fallback) {
+    const n = Number(process.env[name]);
+    return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+function toPositiveInt(value) {
+    const n = typeof value === "number"
+        ? value
+        : typeof value === "string"
+            ? Number(value)
+            : NaN;
+    return Number.isInteger(n) && n >= 1 ? n : undefined;
+}
+/** A NUL byte in the first chunk is a reliable, cheap "this isn't text" signal. */
+function looksBinary(buf) {
+    const n = Math.min(buf.length, 8192);
+    for (let i = 0; i < n; i++) {
+        if (buf[i] === 0)
+            return true;
+    }
+    return false;
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${Math.round(n / 1024)} KB`;
+    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+//# sourceMappingURL=readFile.js.map

package/dist/tools/readFile.js.map

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

package/dist/tools/readSymbol.js

@@ -0,0 +1,145 @@
+/**
+ * readSymbol.ts — read one symbol's definition, not the whole file.
+ *
+ * The token-saving companion to read_file: when the model only needs to see one
+ * function/class/method, this returns exactly that symbol's lines (located via the
+ * code map's LSP `documentSymbol` range, or a tree-sitter span as a fallback)
+ * instead of pulling a 2000-line file to look at 20 lines. read_file and its
+ * whole-file read are unchanged — this is the surgical alternative, and WHEN to
+ * reach for it stays the model's judgment.
+ *
+ * It also records the file as read, so a follow-up edit / replace_symbol_body
+ * clears the read-before-edit gate without a redundant whole-file read.
+ */
+import { promises as fs } from "node:fs";
+import { relativize, resolvePath, nextTouch, markScope } from "./paths.js";
+import { addFocus, coversSpan } from "./focus.js";
+import { allChassis, symbolSpans } from "./chassisMux.js";
+import { sliceBody } from "./spanCore.js";
+import { fail, failQuietly } from "./results.js";
+// Even a single symbol can be huge (a 900-line class). Cap what we return so one
+// read_symbol can't flood the context; the model can read_file a range for more.
+const MAX_SYMBOL_LINES = 400;
+export const readSymbolTool = {
+    name: "read_symbol",
+    readOnly: true,
+    // The description told the model to pass `path` for an ambiguous name without saying
+    // what happens if it does not: the tool LISTS the candidates rather than guessing, so
+    // the first call is always safe and is itself the way to disambiguate. It also never
+    // mentioned that this read satisfies the read-before-edit gate, which is the whole
+    // reason it can replace a full read_file before an edit rather than merely precede one.
+    description: "Read the full definition of a symbol (function, class, method, type, and so on) by " +
+        "name: just its lines, not the whole file. Prefer this over read_file whenever you " +
+        "only need one symbol, since it avoids pulling a large file in to look at a small " +
+        "part of it. " +
+        "THIS COUNTS AS READING THE FILE, so you can edit that symbol straight afterwards " +
+        "without a separate read_file first. " +
+        "If the name is defined in several files it does NOT guess: you get the candidates " +
+        "with their locations, and you pick one with `path`. So calling it without `path` " +
+        "first is safe, and is usually how you find out there was an ambiguity at all. " +
+        `Long symbols stop after ${MAX_SYMBOL_LINES} lines and tell you where to continue ` +
+        "with read_file. Without a language server the match is name-level, and it says so " +
+        "when that is the case.",
+    parameters: {
+        type: "object",
+        additionalProperties: false,
+        required: ["name"],
+        properties: {
+            name: { type: "string", description: "The symbol name to read." },
+            path: {
+                type: "string",
+                description: "File the symbol is in (optional; disambiguates a name defined in several files).",
+            },
+        },
+    },
+    async execute(args, ctx) {
+        const name = typeof args.name === "string" ? args.name.trim() : "";
+        if (!name)
+            return failQuietly("`name` is required.");
+        if (allChassis(ctx).length === 0) {
+            return {
+                output: "The code map isn't available here — use outline, grep, and read_file instead.",
+                summary: "code map unavailable",
+            };
+        }
+        const rawPath = typeof args.path === "string" && args.path.trim() ? args.path.trim() : undefined;
+        const wantAbs = rawPath ? resolvePath(ctx, rawPath) : undefined;
+        const spans = await symbolSpans(ctx, name, wantAbs ? { path: wantAbs } : {});
+        if (spans.length === 0) {
+            return {
+                output: `Couldn't locate a symbol named '${name}'${rawPath ? ` in ${rawPath}` : ""}. ` +
+                    "Use outline to list a file's symbols, or grep for the name.",
+                summary: `read_symbol ${name} — not found`,
+            };
+        }
+        // Defined in several files → list them and ask for a path (don't guess).
+        const files = new Set(spans.map((s) => s.file));
+        if (files.size > 1) {
+            const list = spans
+                .map((s) => `${relativize(ctx, s.file)}:${s.start}-${s.end}  ${s.kind} ${s.name}`)
+                .join("\n");
+            return {
+                output: `'${name}' is defined in several files — pass \`path\` to pick one:\n${list}`,
+                summary: `read_symbol ${name} (${files.size} files)`,
+            };
+        }
+        const span = spans[0];
+        const abs = resolvePath(ctx, span.file);
+        let content;
+        let stat;
+        try {
+            stat = await fs.stat(abs);
+            content = await fs.readFile(abs, "utf8");
+        }
+        catch {
+            return fail(`could not read ${relativize(ctx, span.file)}.`);
+        }
+        const capped = Math.min(span.end, span.start + MAX_SYMBOL_LINES - 1);
+        const body = sliceBody(content, span.start, capped);
+        const truncated = capped < span.end ? `\n… (symbol continues to line ${span.end}; read_file a range for the rest)` : "";
+        const caveat = span.confidence === "name-level"
+            ? "\n(name-level match — verify with grep if exact identity matters)"
+            : "";
+        const shown = relativize(ctx, span.file);
+        // Record the read (ranged) so a follow-up edit clears the read-before-edit gate,
+        // with recency + the symbol's span as focus (for working-set localization).
+        const prior = ctx.reads.get(abs);
+        const unchanged = prior?.mtimeMs === stat.mtimeMs && prior?.size === stat.size;
+        markScope(ctx, abs);
+        ctx.reads.set(abs, {
+            mtimeMs: stat.mtimeMs,
+            size: stat.size,
+            full: false,
+            touchedAt: nextTouch(),
+            focus: addFocus(prior?.focus, { start: span.start, end: span.end }),
+        });
+        // DEDUP, the same contract read_file has had and this tool never did. Once a file
+        // is in the working set, its content is rebuilt into the volatile tail on EVERY
+        // turn — so re-sending a symbol body the model is already looking at pays for the
+        // same lines twice, every time. Measured across terminal coding agents,
+        // repeated reads are ~42% of avoidable token spend, and this was our version of it:
+        // a session re-read the same four functions over and over while all four sat in
+        // <working_files>.
+        //
+        // Checked against what the working set actually PUT ON SCREEN this turn, not
+        // against the read ledger. The ledger records what was read once; it does not
+        // prove the text is still visible, and a sub-agent or a headless run has no
+        // working set at all — so trusting it would tell the model "you already have
+        // this" about content it cannot see. A wasted read is cheap; a phantom one makes
+        // the model work from text it never received. Also requires the file to be
+        // UNCHANGED: after an edit the new body has to come back.
+        const alreadyShown = unchanged && coversSpan(ctx.workingSetSpans?.get(abs), span.start, span.end);
+        if (alreadyShown) {
+            return {
+                output: `${span.kind} ${span.name} — ${shown}:${span.start}-${span.end} is already in your ` +
+                    `<working_files> block, unchanged. Read it there rather than calling this again.`,
+                summary: `${span.name} (already in context)`,
+            };
+        }
+        return {
+            output: `${span.kind} ${span.name} — ${shown}:${span.start}-${span.end}\n${body}${truncated}${caveat}`,
+            summary: `read ${span.name} (${shown}:${span.start}-${span.end})`,
+        };
+    },
+};
+//# sourceMappingURL=readSymbol.js.map

package/dist/tools/readSymbol.js.map

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