Skip to slide
041 / 221

CH 03 · Tool Design · 14/18

Read as one page

Real code: pi's read tool tells the model how to continue

Back to pi. For text, every read result is capped at 2000 lines or 50 KB, whichever comes first. Images skip that cap and are sent as image attachments. A cap alone would leave the model holding half a file with no idea that it is half. Watch how every branch in the excerpt that cuts text ends with a note written for the model.

// Apply truncation, respecting both line and byte limits.
const truncation = truncateHead(selectedContent); // [1]
let outputText: string;
if (truncation.firstLineExceedsLimit) {
  // First line alone exceeds the byte limit. Point the model at a bash fallback.
  const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine], "utf-8"));
  outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`; // [2]
  details = { truncation };
} else if (truncation.truncated) {
  // Truncation occurred. Build an actionable continuation notice.
  const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
  const nextOffset = endLineDisplay + 1;
  outputText = truncation.content;
  if (truncation.truncatedBy === "lines") {
    outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`; // [3]
  } else {
    outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;
  }
  details = { truncation }; // [4]
} else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {
  // User-specified limit stopped early, but the file still has more content.
  const remaining = allLines.length - (startLine + userLimitedLines);
  const nextOffset = startLine + userLimitedLines + 1;
  outputText = `${truncation.content}\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`; // [5]
} else {
  // No truncation and no remaining user-limited content.
  outputText = truncation.content;
}
content = [{ type: "text", text: outputText }];

Source: earendil-works/pi, packages/coding-agent/src/core/tools/read.ts (MIT)

What to notice

  1. [1] selectedContent is the file from the requested offset (a 1-based line number) onward, or only limit lines if the model passed one. truncateHead, in truncate.ts, keeps lines from the top until either cap is hit, and never cuts a line in half.
  2. [2] The edge case: one line bigger than 50 KB, such as a minified bundle. Returning nothing would be useless, so the note hands the model a ready-made command for a different tool, bash: sed -n prints that one line and head -c caps it at 50 KB.
  3. [3] The normal cut. Suppose the model reads a 5,000-line file with no offset, and its first 2000 lines fit in 50 KB (made-up numbers). It gets lines 1 to 2000, then [Showing lines 1-2000 of 5000. Use offset=2001 to continue.]. The model does not have to work out the next argument; the note contains it.
  4. [4] details holds the truncation record, which the read renderer shows in the UI. pi's AgentToolResult type sends only content to the model.
  5. [5] Even when the model chose its own limit, it hears how many lines remain and where to resume.

The description says "Use offset/limit for large files." The note does not repeat that sentence. It attaches the next argument to the data, as in Use offset=2001 to continue. A read tool that silently returned the first 2000 lines would let the model reason about a file it has only partly seen.

Read it yourself: in read.ts, find the description string in createReadToolDefinition and match each instruction in it to the branch above that reinforces it. Then open truncate.ts and read truncateTail, the mirror image of truncateHead. Search the repo for where it is called (bash-executor.ts is one place) and work out why command output keeps its last lines instead of its first.

Finished this idea?

Your learning progress stays in this browser.