pi-supernova 0.8.2 → 0.9.1

package/index.js

@@ -1,158 +1,23 @@
-import { createRequire } from "node:module";
+import {programParameters} from './src/contract/program.js';
+import {progressEmitter} from './src/ui/progress.js';
+export {progressEmitter} from './src/ui/progress.js';
+import {result,errorText,successText,fitOutput,attachReceipts,throwIfFailed} from './src/output/outcome.js';
+
 import { runProgramBatch } from "./src/runtime/program-batch.js";
 import { REFERENCE } from "./src/runtime/reference.js";
-import { isString, isFunction } from "./src/shared/decode.js";
+import { errorMessage, isString } from "./src/shared/decode.js";
 import { loadConfig } from "./src/config/config.js";
 import { createHostBridge } from "./src/bridge/host-bridge.js";
-import { truncateChars, formatBoundedStringArray } from "./src/output/format.js";
+
 import { runGuestProgram, warmGuestWorker, stopWarmGuestWorker } from "./src/runtime/runtime.js";
 import { renderSupernovaCall, renderSupernovaResult } from "./src/ui/render.js";
 
 export { renderSupernovaCall, renderSupernovaResult };
 
-// Sync only, never top-level await. Dynamic import of host/deps hung OMP plugin load.
-const require = createRequire(import.meta.url);
-
-let Type;
-
-try {
-  Type = require("typebox").Type;
-} catch {
-  Type = {
-    Object: (props, opts) => ({ type: "object", properties: props || {}, additionalProperties: false, ...opts }),
-    String: (opts) => ({ type: "string", ...opts }),
-    Unknown: (opts) => ({ ...opts }),
-    Array: (items, opts) => ({ type: "array", items, ...opts }),
-    Integer: (opts) => ({ type: "integer", ...opts }),
-    Optional: (s) => ({ ...s }),
-    Boolean: (opts) => ({ type: "boolean", ...opts }),
-  };
-}
-
-function result(text, details) {
-  return { content: [{ type: "text", text }], details };
-}
-
-const PROGRESS_FRAME_MS = 80;
-
-/**
- * Live trace updates for the card. The first update is immediate (seeds the result slot);
- * later ones are coalesced to one host re-render per frame so a tight loop of nova.calls
- * is not throttled by the TUI. A throwing host callback must never break the run.
- */
-export function progressEmitter(onUpdate) {
-  if (!isFunction(onUpdate)) return Object.assign(() => {}, { flush() {} });
-  let pending = null;
-  let timer = null;
-  let lastSent = -Infinity;
-
-  const send = () => {
-    timer = null;
-
-    if (pending === null) return;
-    // Snapshot only at emission, not on every tool event. Completed records must
-    // not mutate a previously emitted frame while Pi is still consuming it.
-    const trace = pending.map(record => ({ ...record }));
-    pending = null;
-    lastSent = performance.now();
-
-    try {
-      onUpdate({ content: [{ type: "text", text: "" }], details: { trace, running: true } });
-    } catch {}
-  };
-
-  const emit = (trace) => {
-    pending = trace;
-
-    if (timer !== null) return;
-    const wait = PROGRESS_FRAME_MS - (performance.now() - lastSent);
-
-    if (wait <= 0) send();
-    else {
-      timer = setTimeout(send, wait);
-      timer.unref?.();
-    }
-  };
-
-  emit.flush = () => {
-    if (timer !== null) clearTimeout(timer);
-    pending = null;
-    timer = null;
-  };
-
-  return emit;
-}
-
 function sessionStats({ programs, returnedChars }) {
   return `this session: ${programs} programs · ${returnedChars} output characters (not token counts)`;
 }
 
-function logsBlock(outcome, tail = "") {
-  if (!outcome.logs?.length && !outcome.logTruncated) return "";
-
-  return `\n--- logs${outcome.logTruncated ? " [logs truncated]" : ""}\n${outcome.logs?.join("\n") ?? ""}${tail}`;
-}
-
-function mutationText(outcome) {
-  const m = outcome.mutations;
-
-  if (!m) return "";
-  const external = m.external ? "; external calls attempted=" + m.external + ", their side effects cannot be rolled back" : "";
-  const uncertain = m.pendingCommits || m.recoveryFailed ? "; filesystem outcome uncertain: inspect disk and any recovery backups before retrying" : "";
-
-  return "\nmutations: committed=" + m.committed + " rolledBack=" + m.rolledBack + " (file versions)" + external + uncertain;
-}
-
-function mutationReceipts(trace) {
-  if (!Array.isArray(trace)) return "";
-
-  return trace
-    .filter(row => row?.ok && (row.name === "write" || row.name === "edit") && isString(row.resultText) && row.resultText)
-    .map(row => row.resultText)
-    .join("\n");
-}
-
-// Corrective hint, emitted only when a turn actually split. Independent work
-// belongs in one program: a split cannot use the single prewarmed worker and pays
-// one extra spawn per sibling. Costs nothing until it fires, so it needs no room in
-// the tool definition.
-function splitTurnHint(outcome) {
-  return outcome.overlappedTurn ? ` (${outcome.overlappedTurn} supernova calls ran at once; independent work belongs in one program)` : "";
-}
-
-function errorText(outcome, call) {
-  return `error #${call} ${outcome.wallMs}ms${outcome.returnTruncated ? " [output truncated]" : ""}${mutationText(outcome)}${splitTurnHint(outcome)}
-error: ${outcome.error}${logsBlock(outcome)}`;
-}
-
-function successText(outcome, call) {
-  const truncated = outcome.returnTruncated ? " [return truncated]" : "";
-  const hint = outcome.undefinedReturn ? " (no return statement; add `return` to get a value)" : "";
-  const m = outcome.mutations;
-  const showMutations = m && (m.committed || m.rolledBack || m.external || m.pendingCommits || m.recoveryFailed) ? mutationText(outcome) : "";
-
-  return `ok #${call} ${outcome.wallMs}ms${truncated}${showMutations}${splitTurnHint(outcome)}${logsBlock(outcome, "\n--- result")}\n${outcome.resultText}${hint}`;
-}
-
-function fitOutput(outcome, call, limit, format) {
-  let text = format(outcome, call);
-
-  if (text.length <= limit) return text;
-  outcome.returnTruncated = true;
-  const wrapper = format({ ...outcome, resultText: "", logs: [] }, call);
-  const room = Math.max(256, limit - wrapper.length);
-
-  if (Array.isArray(outcome.result) && outcome.result.length && outcome.result.every(isString)) {
-    outcome.resultText = formatBoundedStringArray(outcome.result, room);
-  } else if (isString(outcome.resultText) && outcome.resultText.length > room) {
-    outcome.resultText = truncateChars(outcome.resultText, room, "output").text;
-  }
-
-  text = format(outcome, call);
-
-  return text.length <= limit ? text : truncateChars(text, limit, "output").text;
-}
-
 const TOOL_DESCRIPTION = REFERENCE;
 
 export default function piSupernova(pi) {
@@ -197,7 +62,7 @@ export function registerCodeMode(pi) {
 
   function makeNovaApi(runBridge, cancel) {
     return {
-      call: (name, args) => runBridge.call(name, args),
+      call: (name, args, onItem) => runBridge.call(name, args, onItem),
       callMany: (calls) => runBridge.callMany(calls),
       speculateBegin: () => runBridge.barrier(() => runBridge.beginSpeculation()),
       speculateCommit: () => runBridge.barrier(() => runBridge.commitSpeculation()),
@@ -280,24 +145,6 @@ export function registerCodeMode(pi) {
     scheduleWarm(runController);
   }
 
-  function attachReceipts(outcome, trace) {
-    if (outcome.ok && outcome.result === undefined) {
-      const receipts = mutationReceipts(trace);
-
-      if (receipts) {
-        outcome.resultText = receipts;
-        outcome.undefinedReturn = false;
-      }
-    }
-  }
-
-  function throwIfFailed(outcome, visible, response) {
-    if (outcome.ok) return response;
-    const error = new Error(visible);
-    Object.defineProperty(error,"supernovaResult",{value:response});
-    throw error;
-  }
-
   function packExecuteResult(outcome, call, runBridge, budget, runOpts, peakSeen) {
     if (budget) budget.logLines += outcome.logs?.length ?? 0;
     outcome.overlappedTurn = !runOpts?.parallel && peakSeen > 1 ? peakSeen : 0;
@@ -322,19 +169,7 @@ export function registerCodeMode(pi) {
     label: "Supernova",
     description: TOOL_DESCRIPTION,
     promptSnippet: "read, write, edit, bash",
-    parameters: Type.Object({
-      code: Type.Optional(Type.String({ maxLength: config.maxCodeChars ?? 48000 })),
-      file: Type.Optional(Type.String({ minLength: 1 })),
-      data: Type.Optional(Type.Unknown()),
-      timeoutMs: Type.Optional(Type.Integer({ minimum: 1000 })),
-      programs: Type.Optional(Type.Array(Type.Object({
-        code: Type.Optional(Type.String({ maxLength: config.maxCodeChars ?? 48000 })),
-        file: Type.Optional(Type.String({ minLength: 1 })),
-        data: Type.Optional(Type.Unknown()),
-      }, {additionalProperties:false}), {minItems:1,maxItems:32})),
-      parallel: Type.Optional(Type.Boolean()),
-      mergeData: Type.Optional(Type.Boolean()),
-    }),
+    parameters: programParameters(config),
     // One self-owned result frame is shared by Pi and OMP; renderCall stays empty
     // so separate call/result slots cannot duplicate the lifecycle card.
     renderShell: "self",
@@ -366,7 +201,7 @@ export function registerCodeMode(pi) {
         runBridge.close();
 
         while (runBridge.getOverlayDepth()) runBridge.rollbackSpeculation();
-        outcome = { ok: false, error: error instanceof Error ? error.message : String(error), logs: outcome?.logs ?? [], wallMs: Math.round(performance.now() - started) };
+        outcome = { ok: false, error: errorMessage(error), logs: outcome?.logs ?? [], wallMs: Math.round(performance.now() - started) };
       } finally {
         peakSeen = Math.max(peakSeen, overlapPeak);
         inFlight -= 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-supernova",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "CodeMode for Pi and OMP: read, edit, write and bash, with transactional files, source views and shared-input program batches.",
   "type": "module",
   "author": "AdityaVG13",
@@ -76,6 +76,7 @@
   "homepage": "https://github.com/AdityaVG13/pi-stack/tree/main/packages/pi-supernova#readme",
   "dependencies": {
     "acorn": "^8.18.0",
+    "sharp": "0.35.4",
     "string-width": "^8.2.2"
   }
 }

package/src/adapters/bash.js

@@ -1,5 +1,5 @@
 import * as fs from "node:fs/promises";
-import { isString } from "../shared/decode.js";
+
 import { normalizeBash } from "../contract/bash.js";
 import { sourceForReferences } from "../fs/source-window.js";
 import { resolveWorkspacePath, runCommand, clearPathCache } from "../fs/workspace.js";
@@ -10,38 +10,13 @@ export function createBash(ctx) {
     return stdout && stderr ? stdout + (stdout.endsWith("\n") ? "" : "\n") + stderr : stdout || stderr;
   }
 
-  function isLiteralArgv(params) {
-    return Array.isArray(params?.args) && process.platform !== "win32" && params.args.length === Object.keys(params.args).length && params.args.every(isString);
-  }
-
-  function bashCommand(params, literal) {
-    if (params?.command !== undefined && !isString(params.command)) throw new Error("bash command must be a string");
-    if (literal && (!isString(params.command) || params.args.some(arg => !isString(arg)))) throw new Error("bash argv requires a command string and an array of string args");
-    const command = String(params?.command ?? "");
-
-    if (!command.trim()) throw new Error("bash requires command");
-
-    return command;
-  }
-
-  function parseBash(params) {
-    const literal = isLiteralArgv(params);
-    const command = bashCommand(params, literal);
-
-    return { literal, command, argv: literal ? [command, ...params.args] : ["bash", "-c", command] };
-  }
-
   async function bash(params, signal) {
       params = normalizeBash(params);
       const cwd = getCwd();
-      const { literal, command, argv } = parseBash(params);
-      const targetCwd = params?.cwd ? await resolveWorkspacePath(cwd, params.cwd, "bash cwd", true) : cwd;
-
-      if (params?.cwd !== undefined) {
-        const st = await fs.stat(targetCwd).catch(() => null);
-
-        if (!st?.isDirectory()) throw new Error("bash cwd is not a directory: " + params.cwd);
-      }
+      const command = String(params.command);
+      const literal = Array.isArray(params.args);
+      const argv = literal ? [command, ...params.args] : ["bash", "-c", command];
+      const targetCwd = await commandCwd(params, cwd);
 
       const transactionBarrier = await vfs.prepareExternalMutation("bash");
       let res;
@@ -84,3 +59,12 @@ export function createBash(ctx) {
 
   return { bash };
 }
+
+async function commandCwd(params, cwd) {
+  const target = params.cwd ? await resolveWorkspacePath(cwd, params.cwd, "bash cwd", true) : cwd;
+  if (params.cwd !== undefined) {
+    const stat = await fs.stat(target).catch(() => null);
+    if (!stat?.isDirectory()) throw new Error("bash cwd is not a directory: " + params.cwd);
+  }
+  return target;
+}

package/src/adapters/errors.js

@@ -1,15 +1,7 @@
 export const IMAGE_MAX_BYTES = 20 * 1024 * 1024;
 export const LARGE_FILE_BYTES = 512 * 1024;
+export const TEXT_MAX_BYTES = 64 * 1024 * 1024;
 
-/** Raw path-only reads above these must use json/about/offset/complete. */
-export const RAW_JSON_CHARS = 4096;
-
-export const RAW_SOURCE_CHARS = 8192;
-
-export const RAW_SOURCE_LINES = 160;
-
-/** Routing responses above this fall back to the bound error instead of dumping. */
-export const ROUTING_MAX_CHARS = 4096;
 export const ABOUT_TOKEN_MAX = 16;
 export const IMAGE_MIME = {
   ".png": "image/png",

package/src/adapters/read-focus.js

@@ -0,0 +1,98 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import {tokenizeQuery,stem} from '../context/snap.js';
+import {runCommand} from '../fs/workspace.js';
+import {lineStartIndex,lineTextRange} from '../fs/lines.js';
+import {textResult} from '../shared/result.js';
+export function createFocusedReader(vfs, readBudget) {
+  function aboutStems(about, requireStem) {
+    const tokens = tokenizeQuery(about).tokens;
+
+    if (tokens.length > 16) throw new Error("about is too broad; use at most 16 keywords");
+    const stems = [...new Set(tokens.map(token => stem(token).slice(0, 128)))];
+
+    if (requireStem && !stems.length) throw new Error("about needs at least one searchable keyword");
+
+    return stems;
+  }
+
+  function overlayHits(overlay, stems, signal) {
+    const hits = [];
+    let line = 1;
+    let start = 0;
+
+    while (start <= overlay.length) {
+      signal?.throwIfAborted();
+      const newline = overlay.indexOf("\n", start);
+      const end = newline < 0 ? overlay.length : newline + 1;
+      const row = overlay.slice(start, newline < 0 ? end : newline).replace(/\r$/, "").toLowerCase();
+
+      if (stems.some(st => row.includes(st))) {
+        hits.push(line);
+        if (hits.length >= 200) break;
+      }
+
+      if (end === overlay.length) break;
+      start = end;
+      line++;
+    }
+
+    return { hits, lineCount: line };
+  }
+
+  function overlayWindows(rel, overlay, hits, lineCount, budget) {
+    const out = [];
+    let cursor = 1;
+    let used = 0;
+    let truncated = hits.length >= 200;
+
+    for (const hit of hits) {
+      const from = Math.max(cursor, hit - 3);
+      const first = lineStartIndex(overlay, from);
+      const last = lineTextRange(overlay, Math.min(hit + 3, lineCount)).end;
+      const body = overlay.slice(first, last);
+
+      if (used + body.length > budget) { truncated = true; break; }
+      if (out.length && from > cursor) out.push("...");
+      out.push(`// ${rel}:${from}\n${body}`);
+      used += body.length;
+      cursor = Math.max(cursor, hit + 4);
+    }
+
+    return { out, truncated };
+  }
+
+  async function focusDisk(rel, about, targetPath, stems, budget, signal) {
+    const args = ["rg", "--fixed-strings", "--ignore-case", "--line-number", "--before-context", "3", "--after-context", "3"];
+
+    for (const token of stems) args.push("-e", token);
+    args.push("--", targetPath);
+    const observed = await fs.stat(targetPath);
+    const res = await runCommand(args, { cwd: path.dirname(targetPath), timeoutMs: 15000, maxOutputChars: budget, signal });
+
+    if (res.exitCode === 0 || res.exitCode === 1) await vfs.recordExpected(targetPath, observed);
+    if (res.exitCode === 1) return textResult("// " + rel + " · no matching text\n", { path: targetPath, outputTruncated: false, complete: false });
+    if (res.exitCode !== 0) throw new Error(res.stderr.trim() || `rg exited ${res.exitCode}`);
+    const marker = res.outputTruncated ? "\n[focused read truncated; narrow about or use read(path, line, count)]" : "";
+
+    return textResult("// " + rel + " · focused text windows (not a complete file); read(path, line, count) for raw text\n" + res.stdout + marker,
+      { path: targetPath, outputTruncated: res.outputTruncated, complete: false });
+  }
+
+  async function focusAbout({ rel, about, overlay, targetPath, signal }) {
+    const stems = aboutStems(about, overlay === undefined);
+    const budget = readBudget(false);
+
+    if (overlay === undefined) return focusDisk(rel, about, targetPath, stems, budget, signal);
+    const { hits, lineCount } = overlayHits(overlay, stems, signal);
+    const { out, truncated } = overlayWindows(rel, overlay, hits, lineCount, budget);
+
+    if (!out.length) return textResult("// " + rel + (hits.length
+      ? " · matching text exceeds view budget; first match at line " + hits[0] + "; use read(path, line, count)\n"
+      : " · no matching staged text\n"), { path: targetPath, outputTruncated: truncated, complete: false });
+    const marker = truncated ? "\n[focused read truncated; narrow about or use read(path, line, count)]" : "";
+
+    return textResult("// " + rel + " · focused staged text windows (not a complete file)\n" + out.join("\n") + marker, { path: targetPath, outputTruncated: truncated, complete: false });
+  }
+  return focusAbout;
+}

package/src/adapters/read-image.js

@@ -0,0 +1,51 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import {assertModelImageMime} from '../shared/decode.js';
+import {validateImageBytes} from '../shared/image.js';
+import {IMAGE_MIME,IMAGE_MAX_BYTES,imageTooLarge,missingFile} from './errors.js';
+export function createImageReader(vfs) {
+  async function readImage(rel, targetPath, mime, signal) {
+    const staged = vfs.getOverlay(targetPath);
+
+    if (staged !== undefined) {
+      const size = Buffer.byteLength(staged, "utf8");
+
+      if (size > IMAGE_MAX_BYTES) throw imageTooLarge(rel, size);
+
+      return Buffer.from(staged);
+    }
+
+    let file;
+
+    try { file = await fs.open(targetPath, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0)); }
+    catch (error) {
+      if (error.code === "ENOENT") throw missingFile(targetPath);
+      throw error;
+    }
+
+    try {
+      const stat = await file.stat();
+
+      if (!stat.isFile()) throw new Error("image read requires a regular file: " + targetPath);
+      if (stat.size > IMAGE_MAX_BYTES) throw imageTooLarge(rel, stat.size);
+      const bytes = await file.readFile({ signal });
+      await vfs.recordExpected(targetPath, stat);
+
+      return bytes;
+    } finally { await file.close(); }
+  }
+
+  async function maybeImage(rel, targetPath, signal) {
+    const mime = IMAGE_MIME[path.extname(targetPath).toLowerCase()];
+
+    if (!mime) return null;
+    assertModelImageMime(mime);
+    const bytes = await readImage(rel, targetPath, mime, signal);
+
+    if (bytes.length > IMAGE_MAX_BYTES) throw imageTooLarge(rel, bytes.length);
+    await validateImageBytes(bytes,mime,rel,signal);
+
+    return { content: [{ type: "image", mimeType: mime, data: bytes.toString("base64") }], details: { path: targetPath } };
+  }
+  return maybeImage;
+}

package/src/adapters/read-json.js

@@ -0,0 +1,42 @@
+import {errorMessage} from "../shared/decode.js";
+import {MAX_JSON_BYTES,jsonProjector} from '../fs/json-read.js';
+import {jsonErrorContext} from '../shared/syntax-context.js';
+import {readResult,readValueBytes,MAX_READ_VALUE_BYTES} from '../shared/result.js';
+
+function selectJsonParts(project, document, rel, selectors) {
+  const parts = [];
+  let remaining = MAX_READ_VALUE_BYTES - 32 - selectors.length * 8;
+
+  try {
+    for (const value of project(document)) {
+      remaining -= readValueBytes(value, remaining);
+      parts.push(value);
+    }
+  } catch (error) {
+    throw new Error("JSON selection failed for " + rel + " (" + selectors.join(", ") + "): " + (errorMessage(error)));
+  }
+
+  return {parts, bytes: MAX_READ_VALUE_BYTES - remaining};
+}
+
+/** RFC 8259 lets parsers ignore one leading BOM; files from Windows tools carry it. */
+const stripBom = text => text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+
+async function projectJson(rel, targetPath, params, vfs) {
+  const project = jsonProjector(params.json);
+  const text = stripBom(await vfs.read(targetPath, { maxBytes: MAX_JSON_BYTES, label: "JSON input" }));
+  let document;
+
+  try { document = JSON.parse(text); }
+  catch (error) {
+    throw new Error("invalid JSON in " + rel + ": " + error.message + "; the entire document must parse before projection" + jsonErrorContext(error.message, text));
+  }
+
+  const many = Array.isArray(params.json);
+  const selectors = many ? params.json.map(String) : [params.json === true ? "." : String(params.json)];
+  const {parts, bytes} = selectJsonParts(project, document, rel, selectors);
+
+  return readResult(many ? parts : parts[0], { path: targetPath, json: true, jsonMany: many, complete: true }, "JSON selection: " + rel + " (" + selectors.join(", ") + ")", bytes);
+}
+
+export { projectJson };

package/src/adapters/read-text.js

@@ -0,0 +1,71 @@
+import {isString,isNumber} from '../shared/decode.js';
+import {WorkspaceIndex} from '../context/repo-index.js';
+import {pickSpan} from '../context/spans.js';
+import {outlineFile} from '../context/outline.js';
+import {readResult} from '../shared/result.js';
+import {sliceLinesRaw,sourceLines,contentLineInfo} from '../fs/lines.js';
+import {LARGE_FILE_BYTES,TEXT_MAX_BYTES} from './errors.js';
+import {outlineOptions,recordOutlineOrigins,createReferenceFinder} from './refs.js';
+
+function needsSourceIndex(params,query) {
+  return isString(params.about) || (params.resolve && isString(query));
+}
+
+export function createTextReader(ctx, readWindow) {
+  const {getCwd,vfs,config,index,ledger}=ctx;
+  const referenceFinder=createReferenceFinder(index,vfs);
+
+  async function loadText(targetPath, params, query, signal) {
+    const explicit = isNumber(params.offset) || isNumber(params.limit);
+    const windowed = explicit && params.complete !== true && !isString(params.about) && !isString(query);
+    if (!windowed) {
+      // Whole reads hash the bytes already loaded. Do not read once for a window
+      // and open/hash the entire file a second time just to return the same text.
+      return {text:await vfs.read(targetPath,{maxBytes:TEXT_MAX_BYTES}),windowed:false};
+    }
+    const start = isNumber(params.offset) ? Math.max(1,Math.floor(params.offset)) : 1;
+    const count = isNumber(params.limit) ? Math.max(0,Math.floor(params.limit)) : undefined;
+    const window = await readWindow(targetPath,start,count,TEXT_MAX_BYTES,signal);
+    if (!window.satisfied) throw new Error("read window exceeds " + TEXT_MAX_BYTES + " bytes: " + targetPath + "; request fewer lines or use a bounded parser through bash");
+    return {text:window.text,windowed:true,windowWhole:window.whole};
+  }
+
+  async function maybeOutline(cwd, rel, targetPath, text, params, entry) {
+    if (!isString(params.about)) return null;
+    const outline = entry && outlineFile(entry,rel,params.about,outlineOptions(params,await referenceFinder(cwd,targetPath),config));
+    if (!outline) return null;
+    recordOutlineOrigins(ledger,rel,outline.text);
+    return readResult(outline.text,{path:targetPath,outline:true,expanded:outline.expanded,declarations:outline.declarations});
+  }
+
+  function resolveSpan(entry, sourceLine, query, params) {
+    if (!params.resolve || !isString(query) || !entry) return {offset:params.offset,limit:params.limit,viewComplete:undefined};
+    const span=pickSpan(WorkspaceIndex.spansOf(entry),{line:sourceLine,name:query});
+    if (!span) return {offset:params.offset,limit:params.limit,viewComplete:undefined};
+    const spanLines=span.end-span.start+1;
+    const limit=isNumber(params.limit) ? Math.min(params.limit,spanLines) : spanLines;
+    return {offset:span.start,limit,viewComplete:limit>=spanLines};
+  }
+
+  function textFileResult(rel,targetPath,loaded,span,sliced,firstLine,explicit) {
+    const lines=sliced.length<=LARGE_FILE_BYTES ? sourceLines(sliced) : null;
+    if (lines) ledger.recordOrigin(rel,firstLine,lines,explicit);
+    return readResult(sliced,{path:targetPath,firstLine,lastLine:firstLine+(lines?.length ?? contentLineInfo(sliced).count)-1,
+      sourceChars:sliced.length,complete:loaded.windowed ? loaded.windowWhole : sliced===loaded.text,viewComplete:span.viewComplete});
+  }
+
+  async function readTextFile(targetPath,params,sourceLine,rel,query,signal) {
+    const explicit=isNumber(params.offset)||isNumber(params.limit);
+    const loaded=await loadText(targetPath,params,query,signal);
+    index.touch(rel);
+    const entry=needsSourceIndex(params,query) ? WorkspaceIndex.fromText(targetPath,loaded.text) : null;
+    const outlined=await maybeOutline(getCwd(),rel,targetPath,loaded.text,params,entry);
+    if (outlined) return outlined;
+    const span=resolveSpan(entry,sourceLine,query,params);
+    const firstLine=isNumber(span.offset) ? Math.max(1,Math.floor(span.offset)) : 1;
+    const sliced=loaded.windowed ? loaded.text : sliceLinesRaw(loaded.text,span.offset,span.limit);
+    if (params.complete===true && sliced!==loaded.text) throw new Error("complete:true requires the whole file; remove offset/limit for " + rel);
+    return textFileResult(rel,targetPath,loaded,span,sliced,firstLine,explicit);
+  }
+  return readTextFile;
+}