jev-lens 0.5.0

package/dist/views.js

@@ -0,0 +1,687 @@
+/**
+ * Candidate views of a tool result. Every view is a deterministic subset of the original
+ * text (never generated), with line numbers so the agent can ask for exact ranges later.
+ */
+const CODE_EXT = /\.(js|mjs|cjs|ts|tsx|jsx|py|go|rs|java|kt|kts|rb|php|c|h|cc|cpp|hpp|cs|swift|scala|sh|bash|zsh|lua|sql)$/i;
+const DATA_EXT = /\.(csv|tsv|jsonl|ndjson|log|json|xml|yaml|yml|toml)$/i;
+const PROSE_EXT = /\.(md|txt|rst|adoc)$/i;
+import { displayedFiles } from "./shell-display.js";
+export { displayedFiles } from "./shell-display.js";
+function countLines(text, re, max = 400) {
+    let n = 0;
+    for (const l of text.split("\n", max))
+        if (re.test(l))
+            n++;
+    return n;
+}
+/** Mixed or unknown file types retain the ordinary command policy. */
+export function kindOfFiles(files) {
+    if (files.length === 0)
+        return undefined;
+    if (files.every((f) => CODE_EXT.test(f)))
+        return "code";
+    if (files.every((f) => PROSE_EXT.test(f)))
+        return "prose";
+    return undefined;
+}
+/** Guess what kind of content this is from the tool, its arguments and the text itself. */
+export function detectKind(toolName, args, text) {
+    const a = (args ?? {});
+    const path = typeof a.path === "string" ? a.path : "";
+    if (/^Here's the files and directories up to \d+ levels deep/.test(text) || looksLikePathList(text))
+        return "listing";
+    if (toolName === "bash" || toolName === "powershell") {
+        // Agents that read files with cat/sed/head get the code and prose views, not the command ones.
+        const shown = toolName === "bash" && typeof a.command === "string" ? displayedFiles(a.command) : undefined;
+        const shownKind = shown ? kindOfFiles(shown) : undefined;
+        if (shownKind === "code" && countLines(text, SIG_RE) >= 3)
+            return "code";
+        if (shownKind === "prose" && countLines(text, HEADING_RE) >= 2)
+            return "prose";
+        return "command";
+    }
+    if (toolName === "ls" || toolName === "find" || toolName === "grep")
+        return "listing";
+    if (CODE_EXT.test(path))
+        return "code";
+    if (DATA_EXT.test(path))
+        return "data";
+    if (PROSE_EXT.test(path))
+        return "prose";
+    if (looksRepetitive(text))
+        return "data";
+    if (SIG_RE.test(text))
+        return "code";
+    return "prose";
+}
+/** Mostly lines that are file paths → a directory listing or find output. */
+export function looksLikePathList(text) {
+    const lines = text.split("\n").filter((l) => l.trim()).slice(0, 300);
+    if (lines.length < 15)
+        return false;
+    const pathy = lines.filter((l) => /^\s*[\w./-]+\/[\w./-]*$/.test(l.trim()) || /^\s*\S+\.(py|js|ts|md|json|txt|yml|yaml|toml|cfg|ini|rs|go|java|c|h)$/.test(l.trim())).length;
+    return pathy / lines.length > 0.7;
+}
+/** Many lines with the same delimiter count → tabular or log-like data. */
+export function looksRepetitive(text) {
+    const lines = text.split("\n").filter((l) => l.trim()).slice(0, 200);
+    if (lines.length < 20)
+        return false;
+    const counts = new Map();
+    for (const l of lines) {
+        const sig = `${(l.match(/,/g) || []).length}|${(l.match(/\t/g) || []).length}|${(l.match(/\|/g) || []).length}`;
+        counts.set(sig, (counts.get(sig) || 0) + 1);
+    }
+    const top = Math.max(...counts.values());
+    return top / lines.length > 0.7 && !/^[\s]*[,|\t]*$/.test(lines[0]) && lines[0].length > 0 && (lines[0].includes(",") || lines[0].includes("\t") || lines[0].includes("|"));
+}
+const SIG_RE = /^\s*(export\s+|pub(\([^)]*\))?\s+|public\s+|private\s+|protected\s+|internal\s+|static\s+|final\s+|abstract\s+|async\s+|default\s+|override\s+|open\s+|suspend\s+|inline\s+|data\s+|sealed\s+|enum\s+|annotation\s+|companion\s+|unsafe\s+|const\s+|declare\s+|@\w+(\([^)]*\))?\s+)*(function|class|interface|type|enum|struct|impl|trait|fn|fun|def|object|val|var|let|const|module|namespace|import|from|require|package|use|record|typealias|macro_rules!|mod|static|extern)\b|^\s*(export\s+)?(async\s+)?[A-Za-z_$][\w$]*\s*\([^)]*\)\s*\{?\s*$|^\s*(get|set)\s+\w+\s*\(|^\s*(\w+)\s*[:=]\s*(async\s*)?(\([^)]*\)|\w+)\s*=>|^\s*@\w+|^\s*#\[|^\s*#\s|^\s*\/\*\*|^\s*\*\/|^[A-Za-z_][\w]*\s*=\s*(function|class|\(|require)|^\s*(public|private|protected|static|final|abstract|synchronized|native)\s+[\w<>\[\], ?]+\s+\w+\s*\(/;
+const HEADING_RE = /^\s*(#{1,6}\s|=+\s*$|-+\s*$|\d+\.\s+[A-Z])/;
+const SIGNAL_RE = /\b(error|fail(ed|ing|ure)?|exception|traceback|panic|fatal|warn(ing)?|not ok|✖|✗|denied|refused|missing|cannot|undefined is not|is not defined|no such file|ENOENT|EACCES|timeout|timed out|assert|expected|actual)\b|^\s*at\s+\S+\s+\(|^ℹ\s|^#\s(pass|fail|tests)|failing|Tests:|Suites:|\d+\s+(passed|failed)/i;
+/** Collapse decorative runs (=====, -----, ......) and very long lines so views stay small. */
+export function tidyLine(l) {
+    let out = l.replace(/([=\-_.*#~])\1{24,}/g, (m) => m.slice(0, 24) + "…").replace(/((?:[=\-_.*#~] ){12,})/g, (m) => m.slice(0, 24) + "…").replace(/(\S)[ \t]{8,}(?=\S)/g, "$1  ").trimEnd();
+    if (out.length > 400)
+        out = out.slice(0, 400) + " …";
+    return out;
+}
+function numbered(lines, idx, tidy = false) {
+    const width = String(lines.length).length;
+    const out = [];
+    let prev = -1;
+    for (const i of idx) {
+        if (prev >= 0 && i > prev + 1)
+            out.push(`${" ".repeat(width)}  ⋯ ${i - prev - 1} lines omitted`);
+        out.push(`${String(i + 1).padStart(width)}│ ${tidy ? tidyLine(lines[i]) : lines[i]}`);
+        prev = i;
+    }
+    if (prev >= 0 && prev < lines.length - 1)
+        out.push(`${" ".repeat(width)}  ⋯ ${lines.length - 1 - prev} lines omitted`);
+    return out.join("\n");
+}
+function withContext(lines, hits, ctx) {
+    const keep = new Set();
+    for (const h of hits)
+        for (let i = Math.max(0, h - ctx); i <= Math.min(lines.length - 1, h + ctx); i++)
+            keep.add(i);
+    return [...keep].sort((a, b) => a - b);
+}
+function make(kind, lines, idx, tidy = false) {
+    const text = numbered(lines, idx, tidy);
+    return { kind, text, lines: idx.length, chars: text.length, included: idx.map((i) => i + 1) };
+}
+export function fullView(text) {
+    const lines = text.split("\n");
+    return { kind: "full", text, lines: lines.length, chars: text.length, included: lines.map((_, i) => i + 1) };
+}
+export function headTailView(text, head = 40, tail = 20, tidy = false) {
+    const lines = text.split("\n");
+    if (lines.length <= head + tail + 5)
+        return fullView(text);
+    const idx = [...Array.from({ length: head }, (_, i) => i), ...Array.from({ length: tail }, (_, i) => lines.length - tail + i)];
+    return make("head_tail", lines, idx, tidy);
+}
+/** Code and prose structure: signatures, exports, imports, doc comments, headings. */
+export function outlineView(text, kind) {
+    const lines = text.split("\n");
+    const hits = new Set();
+    const re = kind === "prose" ? HEADING_RE : SIG_RE;
+    for (let i = 0; i < lines.length; i++)
+        if (re.test(lines[i]))
+            hits.add(i);
+    if (kind === "prose")
+        for (let i = 0; i < lines.length; i++)
+            if (hits.has(i) && i + 1 < lines.length && lines[i + 1].trim())
+                hits.add(i + 1);
+    if (hits.size < 3)
+        return headTailView(text);
+    return make("outline", lines, withContext(lines, hits, 0));
+}
+/** Lines mentioning any of the given terms, with context. */
+export function focusView(text, terms, ctx = 3, tidy = false) {
+    const t = terms.map((x) => x.trim()).filter((x) => x.length >= 3);
+    if (t.length === 0)
+        return undefined;
+    const lines = text.split("\n");
+    const hits = new Set();
+    const lowered = t.map((x) => x.toLowerCase());
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i].toLowerCase();
+        if (lowered.some((x) => l.includes(x)))
+            hits.add(i);
+    }
+    if (hits.size === 0)
+        return undefined;
+    const idx = withContext(lines, hits, ctx);
+    if (idx.length >= lines.length * 0.8)
+        return undefined;
+    return make("focus", lines, idx, tidy);
+}
+/** Command output: error/warning/summary lines with context, plus the tail. */
+export function signalsView(text, ctx = 2, tail = 8, tidy = true) {
+    const lines = text.split("\n");
+    const hits = new Set();
+    for (let i = 0; i < lines.length; i++)
+        if (SIGNAL_RE.test(lines[i]))
+            hits.add(i);
+    for (let i = Math.max(0, lines.length - tail); i < lines.length; i++)
+        hits.add(i);
+    const idx = withContext(lines, hits, ctx);
+    if (idx.length >= lines.length * 0.8)
+        return fullView(text);
+    return make("signals", lines, idx, tidy);
+}
+const TEST_MARKERS = /test session starts|passed|failed|FAILED|ERROR|✖|✔|not ok|^ok \d|Tests:|Test Suites:|# (pass|fail|tests)|PASS |FAIL |AssertionError|assert /m;
+const TEST_FAIL_LINE = /^(FAILED|ERROR) |^E\s{2,}|AssertionError|^\s*assert |✖|not ok|^\s+at .*\(|Error:|Exception|Traceback|^\s*File ".*", line \d+/;
+const TEST_SECTION = /^=+ (FAILURES|ERRORS|short test summary info|warnings summary) =+|^_{3,} .* _{3,}$|^(_ ){5,}_?\s*$|^\[\.\.\. Observation truncated|^(ℹ|✖) |^# (Subtest|Failure)/;
+const TEST_SUMMARY = /^=+ .*(passed|failed|error|skipped|deselected|xfailed|no tests ran).* =+$|^(Tests:|Test Suites:|Time:|Ran \d+ tests|OK|FAILED \(|ℹ (pass|fail|tests|duration)|# (pass|fail|tests))/;
+/** Is this command output a test run? */
+export function looksLikeTestLog(text) {
+    const m = text.match(TEST_MARKERS);
+    return !!m && (text.match(/\b(passed|failed|✔|✖|not ok|ok \d)\b/gi) ?? []).length >= 2;
+}
+/**
+ * Test run output reduced to what the agent acts on: the session header, every failing test's
+ * section (test id, assertion, the last frames of its traceback), the short summary, and the
+ * final counts. Passing tests, dots and decorative bars are dropped.
+ */
+export function testlogView(text, ctx = 2, maxFailLines = 60, maxIds = 25) {
+    if (!looksLikeTestLog(text))
+        return undefined;
+    const lines = text.split("\n");
+    const keep = new Set();
+    let inFailures = false;
+    let failLines = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i];
+        if (i < 3)
+            keep.add(i);
+        if (TEST_SECTION.test(l)) {
+            keep.add(i);
+            inFailures = /FAILURES|ERRORS|_{3,}/.test(l) ? true : false;
+            failLines = 0;
+            continue;
+        }
+        if (TEST_SUMMARY.test(l)) {
+            keep.add(i);
+            inFailures = false;
+            continue;
+        }
+        if (TEST_FAIL_LINE.test(l)) {
+            for (let j = Math.max(0, i - ctx); j <= Math.min(lines.length - 1, i + ctx); j++)
+                keep.add(j);
+            continue;
+        }
+        if (inFailures && failLines < maxFailLines && l.trim()) {
+            keep.add(i);
+            failLines++;
+        }
+    }
+    // inside failure sections, drop traceback paragraphs that end in a library frame (site-packages, /opt/conda, /usr/lib):
+    // the agent cannot edit those, and the repo frame plus the E-lines carry the information
+    const LIB = /(site-packages|dist-packages|\/opt\/conda|\/usr\/lib|\/usr\/local\/lib|\.pyenv|\/node_modules\/)/;
+    // A frame runs from the previous boundary (section marker, chain separator or previous footer) to its
+    // footer line "path:line: Error". Library frames lose their source lines; their E-lines (the message) stay.
+    const FOOTER = /^\S+\.(py|js|ts|rb|go|rs|java):\d+: ?\w*$|^\s*File "[^"]+", line \d+/;
+    let boundary = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (TEST_SECTION.test(lines[i]) || TEST_SUMMARY.test(lines[i])) {
+            boundary = i;
+            continue;
+        }
+        if (!FOOTER.test(lines[i]))
+            continue;
+        if (LIB.test(lines[i])) {
+            for (let j = boundary + 1; j <= i; j++)
+                if (keep.has(j) && !/^E\s{2,}/.test(lines[j]))
+                    keep.delete(j);
+        }
+        boundary = i;
+    }
+    // keep a compact index of test ids (agents pick one to re-run), capped so verbose runs stay small
+    let ids = 0;
+    for (let i = 0; i < lines.length && ids < maxIds; i++) {
+        if (keep.has(i))
+            continue;
+        if (/^\S+\.(py|js|ts|rb|go|rs)::\S+ (PASSED|FAILED|ERROR|SKIPPED|XFAIL)/.test(lines[i]) || /^(✔|✓|ok \d+ -) /.test(lines[i])) {
+            keep.add(i);
+            ids++;
+        }
+    }
+    // always keep the last 5 lines (final summary)
+    for (let i = Math.max(0, lines.length - 5); i < lines.length; i++)
+        keep.add(i);
+    const idx = [...keep].sort((a, b) => a - b);
+    if (idx.length >= lines.length * 0.8)
+        return undefined;
+    return make("testlog", lines, idx, true);
+}
+/**
+ * Directory listings and find output: group paths by directory, keep the first entries of each
+ * directory and say how many more there are. Directories with many files (tests, fixtures) collapse.
+ */
+export function treeView(text, perDir = 8, terms = [], tidy = true) {
+    const lines = text.split("\n");
+    const lowered = terms.map((t) => t.toLowerCase()).filter((t) => t.length >= 4);
+    const byDir = new Map();
+    for (let i = 0; i < lines.length; i++) {
+        const t = lines[i].trim();
+        if (!t)
+            continue;
+        const path = t.replace(/\/$/, "");
+        const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+        if (!byDir.has(dir))
+            byDir.set(dir, []);
+        byDir.get(dir).push(i);
+    }
+    if (byDir.size < 2)
+        return undefined;
+    const keep = new Set();
+    for (let i = 0; i < Math.min(2, lines.length); i++)
+        if (!/^\s*[\w./-]+\/?$/.test(lines[i].trim()))
+            keep.add(i);
+    for (const idx of byDir.values())
+        for (const i of idx.slice(0, perDir))
+            keep.add(i);
+    if (lowered.length) {
+        // match terms against the basename only, and ignore terms that match a large share of entries (repo names, common dirs)
+        const bases = lines.map((l) => l.trim().replace(/\/$/, "").split("/").pop()?.toLowerCase() ?? "");
+        for (const t of lowered) {
+            const hits = bases.map((b, i) => (b.includes(t) ? i : -1)).filter((i) => i >= 0);
+            if (hits.length === 0 || hits.length > Math.max(5, lines.length * 0.2))
+                continue;
+            for (const i of hits)
+                keep.add(i);
+        }
+    }
+    const idx = [...keep].sort((a, b) => a - b);
+    if (idx.length >= lines.length * 0.8)
+        return undefined;
+    return make("tree", lines, idx, tidy);
+}
+const GREP_LINE = /^([^:\s][^:]*?):(\d+)[:-]/;
+/**
+ * grep / rg / git grep output (path:line:content): keep the first matches of every file and say how
+ * many more each file has. Files are what the agent navigates by; the tail of a long match list rarely matters.
+ */
+export function matchesView(text, perFile = 6, tidy = true) {
+    const lines = text.split("\n");
+    let grepLines = 0;
+    const byFile = new Map();
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(GREP_LINE);
+        if (!m)
+            continue;
+        grepLines++;
+        if (!byFile.has(m[1]))
+            byFile.set(m[1], []);
+        byFile.get(m[1]).push(i);
+    }
+    const nonEmpty = lines.filter((l) => l.trim()).length;
+    if (grepLines < 10 || grepLines < nonEmpty * 0.6 || byFile.size < 1)
+        return undefined;
+    const keep = new Set();
+    for (let i = 0; i < lines.length; i++)
+        if (!GREP_LINE.test(lines[i]) && lines[i].trim() && !/^--$/.test(lines[i]))
+            keep.add(i); // non-match lines (headers, errors)
+    for (const idx of byFile.values())
+        for (const i of idx.slice(0, perFile))
+            keep.add(i);
+    const idx = [...keep].sort((a, b) => a - b);
+    if (idx.length >= lines.length * 0.8)
+        return undefined;
+    return make("matches", lines, idx, tidy);
+}
+/** Normalise a log line to its template: numbers, hex, timestamps and quoted strings removed. */
+function lineTemplate(l) {
+    return l.replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}[.,]?\d*/g, "<ts>").replace(/0x[0-9a-f]+/gi, "<hex>").replace(/\b\d+(\.\d+)?/g, "<n>").replace(/(["']).*?\1/g, "<str>").trim();
+}
+/**
+ * Log-like output (scripts, servers, repeated progress lines): keep the first two and the last
+ * occurrence of every line template, so repeated lines collapse while the story stays readable.
+ */
+export function logView(text, tidy = true) {
+    const lines = text.split("\n");
+    if (lines.length < 40)
+        return undefined;
+    const seen = new Map();
+    for (let i = 0; i < lines.length; i++) {
+        if (!lines[i].trim())
+            continue;
+        const t = lineTemplate(lines[i]);
+        if (!seen.has(t))
+            seen.set(t, []);
+        seen.get(t).push(i);
+    }
+    // only worth it when templates repeat a lot
+    const repeated = [...seen.values()].filter((v) => v.length >= 3).reduce((a, v) => a + v.length, 0);
+    if (repeated < lines.length * 0.3)
+        return undefined;
+    const keep = new Set();
+    for (const idx of seen.values()) {
+        keep.add(idx[0]);
+        if (idx.length > 1)
+            keep.add(idx[1]);
+        keep.add(idx[idx.length - 1]);
+    }
+    for (let i = 0; i < lines.length; i++)
+        if (SIGNAL_RE.test(lines[i]))
+            keep.add(i);
+    for (let i = Math.max(0, lines.length - 5); i < lines.length; i++)
+        keep.add(i);
+    const idx = [...keep].sort((a, b) => a - b);
+    if (idx.length >= lines.length * 0.8)
+        return undefined;
+    return make("log", lines, idx, tidy);
+}
+/** Data files: header plus a sample of rows and the count. */
+export function sampleView(text, rows = 12, tidy = true) {
+    const lines = text.split("\n");
+    if (lines.length <= rows + 6)
+        return fullView(text);
+    const idx = [...Array.from({ length: rows }, (_, i) => i), lines.length - 2, lines.length - 1].filter((i, k, arr) => i >= 0 && arr.indexOf(i) === k);
+    return make("sample", lines, idx, tidy);
+}
+/** Pull identifier-like terms out of task text and tool arguments to drive the focus view. */
+export function extractTerms(...texts) {
+    const found = new Map();
+    for (const t of texts) {
+        for (const m of t.matchAll(/[A-Za-z_$][A-Za-z0-9_$]{3,}/g)) {
+            const w = m[0];
+            if (STOP.has(w.toLowerCase()))
+                continue;
+            if (/^[A-Z][a-z]+$/.test(w) && w.length < 8)
+                continue; // capitalised common words
+            found.set(w, (found.get(w) || 0) + 1);
+        }
+        for (const m of t.matchAll(/`([^`\n]{3,60})`/g))
+            found.set(m[1], (found.get(m[1]) || 0) + 3);
+        for (const m of t.matchAll(/["']([^"'\n]{4,60})["']/g))
+            found.set(m[1], (found.get(m[1]) || 0) + 2);
+    }
+    return [...found.entries()]
+        .filter(([w]) => /[a-z]/.test(w) && (/[A-Z_.$]/.test(w.slice(1)) || w.length >= 8))
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 25)
+        .map(([w]) => w);
+}
+const STOP = new Set("this that with from have will would should could there their about which where when what make sure does into then than only also just some more most such each other after before because while please tests test file files function functions module modules code change changes changed running return returns using used uses need needs needed does must keep keeps always never every existing behaviour behavior following current update updated added adding delete remove rename renamed read write import export const class type string number object array value values default defaults lines line".split(/\s+/));
+export const DEFAULT_VIEW_PARAMS = { headLines: 40, tailLines: 20, focusCtx: 3, sampleRows: 12, signalsCtx: 1, signalsTail: 8, testIds: 25, testFailLines: 60, matchesPerFile: 6, logView: true, sectionsView: true, sectionMinLines: 3, sectionMaxBlocks: 24, sectionChunkLines: 50, minShrink: 0.6 };
+/** Build the candidate views for a tool result. Full is always first. Views that do not shrink the text enough are dropped. */
+export function buildCandidates(toolName, args, text, terms, params = {}) {
+    const P = { ...DEFAULT_VIEW_PARAMS, ...params };
+    const kind = detectKind(toolName, args, text);
+    const full = fullView(text);
+    const cands = [full];
+    // The agent's own edit/write results echo the file it is working on and will edit again: never reduce them.
+    if (toolName === "edit" || toolName === "write" || toolName === "str_replace_editor")
+        return { kind, views: cands };
+    const add = (v) => {
+        if (!v || v.kind === "full")
+            return;
+        if (v.chars > full.chars * P.minShrink)
+            return;
+        if (cands.some((c) => c.kind === v.kind))
+            return;
+        cands.push(v);
+    };
+    // Code and prose views keep every retained line exactly, so an edit whose oldText was copied from the view
+    // still matches the file. Command, listing and data output is never edited, so decorative bars, long runs
+    // of spaces and very long lines are shortened there (tidyLine); that is what keeps signals/log views small.
+    const tidy = kind === "command" || kind === "listing" || kind === "data";
+    if (kind === "code" || kind === "prose")
+        add(outlineView(text, kind));
+    if (kind === "command")
+        add(testlogView(text, P.signalsCtx, P.testFailLines, P.testIds));
+    if (kind === "command" || kind === "listing")
+        add(matchesView(text, P.matchesPerFile, tidy));
+    if (kind === "command" && P.logView)
+        add(logView(text, tidy));
+    // A plain file display that stayed "command" (mixed file types) may still be edited from: no section headers for it.
+    const isFileDisplay = kind === "command" && typeof args?.command === "string" && displayedFiles(args.command) !== undefined;
+    if (kind === "command" && P.sectionsView && !isFileDisplay)
+        add(sectionsView(text, splitSections(text, P.sectionMinLines, P.sectionMaxBlocks, P.sectionChunkLines), tidy));
+    if (kind === "listing")
+        add(treeView(text, 8, terms, tidy));
+    if (kind === "command" || kind === "listing")
+        add(signalsView(text, P.signalsCtx, P.signalsTail, tidy));
+    if (kind === "data")
+        add(sampleView(text, P.sampleRows, tidy));
+    add(focusView(text, terms, P.focusCtx, tidy));
+    add(headTailView(text, P.headLines, P.tailLines, tidy));
+    return { kind, views: cands };
+}
+export function footer(view, toolCallId, total, opts = {}) {
+    if (view.kind === "full")
+        return "";
+    const recall = opts.recall ? opts.recall(toolCallId) : `Call recall(id: "${toolCallId}") for the full output, or recall(id, lines: "a-b") / recall(id, pattern: "...") for a slice.`;
+    return `\n\n[jev-lens: showing the "${view.kind}" view, ${view.lines} of ${total} lines. Omitted lines are marked ⋯. ${recall}${opts.note ? ` ${opts.note}` : ""}]`;
+}
+/**
+ * Split code into top-level blocks: each block starts at a signature line with no indentation
+ * (or the least indentation seen) and runs until the next one. Leading imports form one block.
+ */
+export function splitBlocks(text, maxBlocks = 32) {
+    const lines = text.split("\n");
+    const starts = [];
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i];
+        if (!l.trim())
+            continue;
+        if (/^\S/.test(l) && SIG_RE.test(l) && !/^\s*(import|from|require|use|package)\b/.test(l) && !/^\s*(\/\*\*|\*\/|\*|#|\/\/)/.test(l))
+            starts.push(i);
+    }
+    if (starts.length < 2)
+        return [];
+    const blocks = [];
+    if (starts[0] > 0)
+        blocks.push({ name: "(header: imports, constants)", from: 1, to: starts[0] });
+    for (let k = 0; k < starts.length; k++) {
+        const from = starts[k];
+        let to = k + 1 < starts.length ? starts[k + 1] - 1 : lines.length - 1;
+        // give a preceding doc comment to the block it documents
+        blocks.push({ name: lines[from].trim().slice(0, 120), from: from + 1, to: to + 1 });
+    }
+    for (let k = 1; k < blocks.length; k++) {
+        const prevEnd = blocks[k - 1].to;
+        let j = prevEnd - 1;
+        while (j >= blocks[k - 1].from && /^\s*(\/\*\*|\*|\/\/|#)/.test(lines[j]))
+            j--;
+        if (j < prevEnd - 1 && j + 1 > blocks[k - 1].from - 1) {
+            blocks[k].from = j + 2;
+            blocks[k - 1].to = j + 1;
+        }
+    }
+    return blocks.slice(0, maxBlocks);
+}
+const SECTION_MARK_RE = /^(?:#{1,6}\s|\*{3,}\s*$|={3,}|-{3,}\s*$|_{3,}\s*$|(?:COMMAND|URL|EXIT|FILE|STEP|TEST|RUN|Traceback \(most recent call last\)|Error|ERROR|WARNING|Warning)\b|[A-Z][A-Z0-9 _-]{2,40}:\s*\S|\[[^\]]{1,60}\]\s*$|Running |Collecting |Installing |Processing )/;
+const GREP_PREFIX_RE = /^([^\s:]+?)[-:](\d+)[-:]/;
+const TRIVIAL_LINE_RE = /^\s*(?:[{}\[\]],?|---|```\w*.*|--|\*{3,}|={3,}|-{3,})\s*$/;
+/**
+ * Split command output into sections: grep context groups (separated by `--` or a change of file), the
+ * top-level keys or items of a JSON document, markdown headings, marker lines (COMMAND:, URL:, ALL-CAPS labels,
+ * ===== bars, tracebacks) and paragraphs separated by blank lines. Small sections are merged into their
+ * predecessor; at most maxBlocks sections are kept. Output with no structure at all falls back to fixed chunks.
+ */
+export function splitSections(text, minLines = 3, maxBlocks = 24, chunkLines = 50) {
+    const lines = text.split("\n");
+    if (lines.length < 6)
+        return [];
+    const starts = [];
+    let prevBlank = true, prevFile = "", afterSep = false;
+    // JSON: inside a top-level { or [ at column 0, every line at the first indentation level starts a section
+    let jsonIndent = -1, inJson = false;
+    for (let i = 0; i < lines.length; i++) {
+        const l = lines[i];
+        const blank = !l.trim();
+        let start = false;
+        if (!blank) {
+            if (/^[\[{]\s*$/.test(l)) {
+                start = true;
+                inJson = true;
+                jsonIndent = -1;
+            }
+            else if (inJson) {
+                if (/^[\]}],?\s*$/.test(l)) {
+                    inJson = false;
+                }
+                else {
+                    const indent = l.length - l.trimStart().length;
+                    if (jsonIndent < 0 && indent > 0)
+                        jsonIndent = indent;
+                    if (indent === jsonIndent && /^\s*(?:"|\{|\[|[\w-]+:)/.test(l))
+                        start = true;
+                }
+            }
+            if (!inJson) {
+                if (prevBlank || afterSep)
+                    start = true;
+                if (l === "--") {
+                    start = false;
+                    afterSep = true;
+                } // grep separator: ends the group before it
+                else
+                    afterSep = false;
+                const g = GREP_PREFIX_RE.exec(l);
+                if (g) {
+                    if (g[1] !== prevFile)
+                        start = true;
+                    prevFile = g[1];
+                }
+                else if (!/^\s/.test(l) && SECTION_MARK_RE.test(l))
+                    start = true;
+            }
+        }
+        if (start && starts[starts.length - 1] !== i)
+            starts.push(i);
+        prevBlank = blank;
+    }
+    if (starts.length < 2 && chunkLines > 0 && lines.length >= chunkLines * 2) {
+        starts.length = 0;
+        for (let i = 0; i < lines.length; i += chunkLines)
+            starts.push(i);
+    }
+    if (starts.length === 0 || starts[0] !== 0)
+        starts.unshift(0);
+    let blocks = starts.map((from, k) => ({ name: "", from: from + 1, to: (k + 1 < starts.length ? starts[k + 1] : lines.length) }));
+    // a section made only of braces, fences or bars belongs to the section after it
+    for (let k = 0; k + 1 < blocks.length; k++) {
+        if (lines.slice(blocks[k].from - 1, blocks[k].to).every((l) => !l.trim() || TRIVIAL_LINE_RE.test(l))) {
+            blocks[k + 1].from = blocks[k].from;
+            blocks[k].to = 0;
+        }
+    }
+    blocks = blocks.filter((b) => b.to > 0);
+    // merge sections that are too small into their predecessor
+    const merged = [];
+    for (const b of blocks) {
+        const last = merged[merged.length - 1];
+        if (last && b.to - b.from + 1 < minLines)
+            last.to = b.to;
+        else
+            merged.push({ ...b });
+    }
+    blocks = merged;
+    // cap the count by merging adjacent sections evenly
+    while (blocks.length > maxBlocks) {
+        const next = [];
+        for (let k = 0; k < blocks.length; k += 2)
+            next.push(k + 1 < blocks.length ? { name: "", from: blocks[k].from, to: blocks[k + 1].to } : blocks[k]);
+        blocks = next;
+    }
+    if (blocks.length < 2)
+        return [];
+    for (const b of blocks)
+        b.name = sectionName(lines, b);
+    return blocks;
+}
+/** First meaningful line of a section; a bare brace, fence or bar is joined with the line after it. */
+function sectionName(lines, b) {
+    const body = lines.slice(b.from - 1, b.to).filter((l) => l.trim());
+    const first = body[0] ?? "";
+    if (TRIVIAL_LINE_RE.test(first) && body[1])
+        return tidyLine(`${first.trim()} ${body[1].trim()}`).slice(0, 120);
+    return tidyLine(first).trim().slice(0, 120);
+}
+/** The first non-empty line of every section, line-numbered, with omission markers between. */
+export function sectionsView(text, blocks, tidy = true) {
+    if (blocks.length < 2)
+        return undefined;
+    const lines = text.split("\n");
+    const idx = [];
+    for (const b of blocks) {
+        let i = b.from - 1;
+        while (i < b.to - 1 && (!lines[i].trim() || lines[i] === "--"))
+            i++;
+        idx.push(i);
+    }
+    return make("sections", lines, idx, tidy);
+}
+/** Outline plus the full bodies of the chosen blocks. */
+export function relevantView(text, kind, blocks, expand, outlineIncluded) {
+    const lines = text.split("\n");
+    const outline = outlineIncluded ? { included: outlineIncluded } : outlineView(text, kind);
+    const idx = new Set(outline.included.map((n) => n - 1));
+    for (const b of expand) {
+        const blk = blocks[b];
+        if (!blk)
+            continue;
+        for (let i = blk.from - 1; i <= blk.to - 1; i++)
+            idx.add(i);
+    }
+    return make("relevant", lines, [...idx].sort((a, b) => a - b));
+}
+/**
+ * Async variant of buildCandidates that uses tree-sitter for the outline of code files when the
+ * grammar is available, and returns the blocks so the second step can reuse them.
+ */
+export async function buildCandidatesAsync(toolName, args, text, terms, params = {}) {
+    const minShrink = params.minShrink ?? DEFAULT_VIEW_PARAMS.minShrink;
+    const base = buildCandidates(toolName, args, text, terms, params);
+    if (base.views.length < 2)
+        return base; // nothing to choose from (e.g. the agent's own edit/write results)
+    if (base.kind === "command") {
+        const P = { ...DEFAULT_VIEW_PARAMS, ...params };
+        const blocks = base.views.some((v) => v.kind === "sections") ? splitSections(text, P.sectionMinLines, P.sectionMaxBlocks, P.sectionChunkLines) : [];
+        return { ...base, blocks: blocks.length >= 2 ? blocks : undefined };
+    }
+    if (base.kind !== "code")
+        return base;
+    try {
+        const { languageForPath, treeSitterBlocks, treeSitterOutline } = await import("./treesitter.js");
+        const path = grammarPath(args, languageForPath);
+        if (!path)
+            return base;
+        const [blocks, outlineIdx] = await Promise.all([treeSitterBlocks(path, text), treeSitterOutline(path, text)]);
+        if (!outlineIdx || outlineIdx.length < 2)
+            return { ...base, blocks: blocks ?? undefined };
+        const lines = text.split("\n");
+        const full = base.views[0];
+        const outline = make("outline", lines, outlineIdx);
+        const views = base.views.filter((v) => v.kind !== "outline");
+        if (outline.chars <= full.chars * minShrink)
+            views.splice(1, 0, outline);
+        return { kind: base.kind, views, blocks: blocks ?? undefined };
+    }
+    catch {
+        return base;
+    }
+}
+/**
+ * The path whose grammar should parse this result: the read path, or, for a shell display command,
+ * the first shown file when every shown file is in the same language (concatenated same-language files parse fine).
+ */
+function grammarPath(args, languageForPath) {
+    const a = (args ?? {});
+    if (typeof a.path === "string")
+        return a.path;
+    if (typeof a.command !== "string")
+        return undefined;
+    const files = displayedFiles(a.command);
+    if (!files)
+        return undefined;
+    const lang = languageForPath(files[0]);
+    if (!lang || files.some((f) => languageForPath(f) !== lang))
+        return undefined;
+    return files[0];
+}