CH 03 · Tool Design · 09/18
Read as one pageReal code: pi's edit tool takes many edits in one call
pi is a minimal coding agent written in TypeScript. The edit tool's schema and execution live in edit.ts. The matching rules live next to it in edit-diff.ts. The schema the model sees has no way to send a single replacement except as a list of one. Watch how it decides what each edit is matched against.
const replaceEditSchema = Type.Object(
{
oldText: Type.String({
description:
"Exact text for one targeted replacement. It must be unique in the original file and must not overlap with any other edits[].oldText in the same call.", // [1]
}),
newText: Type.String({ description: "Replacement text for this targeted edit." }),
},
{},
);
const editSchema = Type.Object(
{
path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
edits: Type.Array(replaceEditSchema, { // [2]
description:
"One or more targeted replacements. Each edit is matched against the original file, not incrementally. Do not include overlapping or nested edits. If two changes touch the same block or nearby lines, merge them into one edit instead.", // [3]
}),
},
{},
);
export const editToolSystemPromptContribution = {
snippet: "Make precise file edits with exact text replacement, including multiple disjoint edits in one call",
guidelines: [
"Use edit for precise changes (edits[].oldText must match exactly)",
"When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls", // [4]
// ... (2 lines: match against the original; keep oldText small)
],
} as const;
Source: earendil-works/pi, packages/coding-agent/src/core/tools/edit.ts (MIT)
What to notice
- [1]
Type.ObjectandType.Stringcome from TypeBox, a library that builds JSON Schema from TypeScript code. Each edit is anoldText(the exact text to find) and anewText(what to put there), and the matching rule lives in the field description. - [2]
editsis an array, so one call can carry any number of replacements to one file. - [3] Every edit is matched against the original file, so the model never has to predict the file halfway through its own batch. Exact
indexOfruns first. A miss is retried after trailing whitespace, smart quotes, Unicode dashes, and special spaces are normalized. Only if that also fails does it throw. Duplicates are counted in that same normalized text, so two regions that differ only by a trailing space count as duplicates. Overlaps are rejected next. Replacements run only after every edit is accepted, and a throw happens beforewriteFile, so a batch lands completely or not at all. For more than one edit the duplicate error readsFound 2 occurrences of edits[1] in src/app.ts. Each oldText must be unique. Please provide more context to make it unique.(the path, the count, and the 0-based index are examples). A one-edit call uses a shorter sentence that does not sayedits[1]. - [4]
editToolSystemPromptContributionfeeds pi's system prompt:buildRulesinsystem-prompt.tsturns each active tool's guidelines into bullet rules. A schema that allows batching does not make the model batch; this guideline tells it when to.
One recommendation from the section is missing: nothing caps the length of edits. Here the file itself bounds the batch, since every oldText must be unique and disjoint within it.
Read it yourself: in edit.ts, scroll to prepareEditArguments. List the four inputs it repairs: a JSON string of an array, a JSON string of one {oldText, newText} object, that object already parsed, and a legacy top-level oldText plus newText appended onto edits. The AgentTool type in packages/agent/src/types.ts says prepareArguments runs before schema validation. Then open edit-diff.ts, find the overlap check, and write two edits that would trigger it. Predict the error message before you read it.
Finished this idea?
Your learning progress stays in this browser.