@xynogen/pix-edit 0.2.17 → 0.2.18

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-edit",
-	"version": "0.2.17",
+	"version": "0.2.18",
 	"description": "Pi tool — precise text replacement edit with diff rendering",
 	"type": "module",
 	"main": "src/index.ts",
@@ -13,13 +13,16 @@
 	},
 	"files": [
 		"src",
-		"!src/**/*.test.*",
 		"README.md",
-		"LICENSE"
+		"LICENSE",
+		"skills"
 	],
 	"pi": {
 		"extensions": [
 			"src/extension.ts"
+		],
+		"skills": [
+			"./skills"
 		]
 	},
 	"keywords": [
@@ -39,8 +42,8 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@xynogen/pix-pretty": "^2.0.0",
-		"@xynogen/pix-runtime": "^0.19.0"
+		"@xynogen/pix-pretty": "^2.1.0",
+		"@xynogen/pix-runtime": "^0.20.0"
 	},
 	"peerDependencies": {
 		"typebox": "*",

package/skills/pix-edit.md

@@ -0,0 +1,46 @@
+---
+name: pix-edit
+description: How to use `edit` without retries — hash anchors from a fresh `read`, one non-overlapping batch per file, and the exact-text fallback. Use before multi-hunk edits, after an edit failed or applied only partly, or when a file may have changed.
+disable-model-invocation: true
+---
+# edit — hash-anchor edits
+
+`edit` was the second most error-prone tool in history (898 errors in 11,315 calls). Nearly all came from four causes below.
+
+## Formats
+
+Hash anchors (preferred), from the `LINE#HASH` prefixes that `read` returns:
+
+```json
+{ "path": "src/a.ts", "edits": [
+  { "op": "replace", "pos": "12#A1F", "end": "14#C03", "lines": ["new line 12", "new line 13"] },
+  { "op": "insert_after", "pos": "40#9B2", "lines": ["added"] }
+] }
+```
+
+- `op`: `replace`, `insert_before`, or `insert_after`. `end` is for `replace` only.
+- `lines` holds raw source lines: no `LINE#HASH|` prefix and no newline characters. An empty array deletes.
+
+Exact text (fallback only after a hash edit fails): `{ "oldText": "...", "newText": "..." }`. `oldText` must match exactly once.
+
+## Avoid the four common failures
+
+| Error in history | Count | Fix |
+|---|---|---|
+| "Edit without read" | 293 | `read` the region in this session before editing it. |
+| "target not found" / stale anchor | 77+ | The file changed. Use the "Current anchors" from the last edit result, or `read` again. Never guess a hash. |
+| "PARTIAL APPLY" | 100+ | Edits in one call must not overlap and must all target the original file. Split dependent changes into separate calls. |
+| schema: `edits.N` must be object / additional properties / `op` | 59 | Never mix hash and exact-text items in one call. Do not add fields such as `text` or `content`. |
+
+## Pattern
+
+1. `read` the lines you will change (use `offset`/`limit`, or `ast` `outline` then `symbol` for code).
+2. Put every independent change to that file in one `edit` call.
+3. Use the "Current anchors" in the result for the next edit to the same region.
+4. Read the "LSP after edit" note. Fix new errors before moving on.
+
+## Do not
+
+- Use `sed -i`, `perl -pi`, or a heredoc in `bash` to change files.
+- Use `write` to change a few lines of an existing file. `write` is for new files and complete rewrites.
+- Retry the same failed edit unchanged. Read the error, then fix the anchor or the format.

package/src/edit.ts

@@ -1,10 +1,3 @@
-import type {
-	AgentToolUpdateCallback,
-	EditToolInput,
-	ExtensionContext,
-	ToolRenderResultOptions,
-} from "@earendil-works/pi-coding-agent";
-import { resolveBaseBackground } from "@xynogen/pix-pretty/ansi";
 import { MAX_RENDER_LINES } from "@xynogen/pix-pretty/config";
 import type { ToolContext } from "@xynogen/pix-pretty/context";
 import { parseDiff } from "@xynogen/pix-pretty/diff";
@@ -16,13 +9,12 @@ import {
 	summarize,
 } from "@xynogen/pix-pretty/diff-render";
 import { lang } from "@xynogen/pix-pretty/lang";
+import { toolCallRenderer, toolCardRenderer } from "@xynogen/pix-pretty/tool-card";
 import type {
 	EditOperation,
 	EditParams,
 	EditRenderState,
 	PiPrettyApi,
-	RenderContextLike,
-	ThemeLike,
 	ToolFactory,
 	ToolResultLike,
 } from "@xynogen/pix-pretty/types";
@@ -30,19 +22,12 @@ import {
 	BODY_PAD,
 	dotJoin,
 	fillToolBackground,
-	frameToolResult,
 	getErrorMessage,
-	getTextContent,
-	hideCollapsedToolCall,
 	isTextContent,
-	renderCollapsed,
 	renderTitle,
-	renderToolError,
 	setResultDetails,
 	termW,
-	unframeToolResult,
 } from "@xynogen/pix-pretty/utils";
-import { type CollapseState, tickCollapse } from "@xynogen/pix-runtime/collapse";
 import {
 	type EditInput,
 	editPath,
@@ -51,6 +36,11 @@ import {
 	type HashParams,
 	prepareEditArguments,
 } from "@xynogen/pix-runtime/files";
+import type {
+	AgentToolUpdateCallback,
+	EditToolInput,
+	ExtensionContext,
+} from "@xynogen/pix-runtime/host";
 
 export {
 	editPath,
@@ -126,7 +116,7 @@ export function registerEditTool(
 		parameters: editSchema,
 		promptSnippet: "Edit with hash anchors first; exact text only after failure",
 		promptGuidelines: [
-			"For edit, try hash anchors from read first. Only if the hash-anchor edit fails, fall back to oldText/newText. If the file changed, read the affected region again before using current source text; never guess anchors or overwrite unseen changes.",
+			'For edit, try hash anchors from read first. Only if the hash-anchor edit fails, fall back to oldText/newText. If the file changed, read the affected region again before using current source text; never guess anchors or overwrite unseen changes. After a failed or partial edit, load read_skills(name="pix-edit", full=true).',
 		],
 		prepareArguments: prepareEditArguments,
 		constrainedSampling: { type: "json_schema", strict: "prefer" },
@@ -212,71 +202,39 @@ export function registerEditTool(
 			return result;
 		},
 
-		renderCall(
-			args: EditParams & Partial<HashParams>,
-			theme: ThemeLike,
-			renderCtx: RenderContextLike<EditRenderState>,
-		) {
-			resolveBaseBackground(theme);
-			const fp = args?.path ?? args?.file_path ?? "";
-			const operations = getEditOperations(args);
-			const text = renderCtx.lastComponent ?? new TextComponent("", 0, 0);
-			if (
-				hideCollapsedToolCall(renderCtx.state as CollapseState, renderCtx.expanded, (value) =>
-					text.setText(value),
-				)
-			)
-				return text;
-			const hdr = `${renderTitle(theme, "edit", renderCtx)} ${theme.fg("dim", sp(fp))}`;
-
-			if (Array.isArray(args.edits) && args.edits.some((edit) => "pos" in edit)) {
-				text.setText(
-					fillToolBackground(dotJoin([hdr, theme.fg("muted", `${args.edits.length} operations`)])),
-				);
-				return text;
-			}
-			if (operations.length === 0) {
-				text.setText(fillToolBackground(hdr));
-				return text;
-			}
+		renderCall: toolCallRenderer<EditParams & Partial<HashParams>, EditRenderState>(
+			TextComponent,
+			(args, theme, renderCtx) => {
+				const fp = args?.path ?? args?.file_path ?? "";
+				const operations = getEditOperations(args);
+				const hdr = `${renderTitle(theme, "edit", renderCtx)} ${theme.fg("dim", sp(fp))}`;
 
-			const { summary } = summarizeEditOperations(operations);
-			const coloredSummary = renderDiffSummary(summary, theme);
-			const paint = (s: string) => theme.fg("muted", s);
-			const suffix = dotJoin(
-				[
-					hdr,
-					operations.length > 1 && theme.fg("muted", `${operations.length} edits`),
-					theme.fg("muted", "estimate"),
-					coloredSummary,
-				],
-				paint,
-			);
-			text.setText(fillToolBackground(suffix));
-			return text;
-		},
+				if (Array.isArray(args.edits) && args.edits.some((edit) => "pos" in edit))
+					return fillToolBackground(
+						dotJoin([hdr, theme.fg("muted", `${args.edits.length} operations`)]),
+					);
+				if (operations.length === 0) return fillToolBackground(hdr);
 
-		renderResult(
-			result: ToolResultLike,
-			_opt: ToolRenderResultOptions,
-			theme: ThemeLike,
-			renderCtx: RenderContextLike<EditRenderState>,
-		) {
-			resolveBaseBackground(theme);
-			const text = unframeToolResult(renderCtx.lastComponent ?? new TextComponent("", 0, 0));
-			const d = result.details as Record<string, unknown> | undefined;
-			const isPartial = _opt?.isPartial === true;
-			const completed = () => frameToolResult(text, theme, renderCtx.isError);
-			const structuredError =
-				renderCtx.isError && (d?._type === "editInfo" || d?._type === "multiEditInfo");
-			if (renderCtx.isError && (!structuredError || isPartial)) {
-				text.setText(renderToolError(getTextContent(result) || "Error", theme));
-				return isPartial ? text : completed();
-			}
+				const { summary } = summarizeEditOperations(operations);
+				const coloredSummary = renderDiffSummary(summary, theme);
+				const paint = (s: string) => theme.fg("muted", s);
+				const suffix = dotJoin(
+					[
+						hdr,
+						operations.length > 1 && theme.fg("muted", `${operations.length} edits`),
+						theme.fg("muted", "estimate"),
+						coloredSummary,
+					],
+					paint,
+				);
+				return fillToolBackground(suffix);
+			},
+		),
 
-			// Auto-collapse: show summary line after delay
-			const cs = renderCtx.state as CollapseState;
-			if (!isPartial && tickCollapse("edit", cs, renderCtx.invalidate, renderCtx.expanded)) {
+		renderResult: toolCardRenderer<Record<string, unknown>, EditRenderState>(TextComponent, {
+			name: "edit",
+			owns: (d) => d?._type === "editInfo" || d?._type === "multiEditInfo",
+			collapsed(d) {
 				const summary =
 					d?._type === "editInfo"
 						? (d.summary as string)
@@ -289,98 +247,85 @@ export function registerEditTool(
 					const ops = d.ops as Array<Record<string, unknown>> | undefined;
 					filePath = String(ops?.[0]?.filePath ?? "");
 				}
-				text.setText(
-					renderCollapsed(
-						theme,
-						"edit",
-						sp(filePath),
-						renderCtx.isError ? "failed" : summary,
-						renderCtx.isError ? "error" : "success",
-					),
-				);
-				return text;
-			}
-
-			if (renderCtx.isError) {
-				text.setText(renderToolError(getTextContent(result) || "Error", theme));
-				return completed();
-			}
-
-			// Single edit — full split diff
-			if (d?._type === "editInfo") {
-				const key = `ed:${diffThemeCacheKey(theme)}:${termW()}:${d.summary}:${(d.oldContent as string).length}:${(d.newContent as string).length}:${d.language ?? ""}`;
-				if (renderCtx.toolCallId) trackInvalidator(renderCtx.toolCallId, renderCtx.invalidate);
-				if (renderCtx.state._edk !== key) {
-					renderCtx.state._edk = key;
-					// ponytail: call already shows `edit <file> <summary>`; don't repeat summary+loc header — gutter carries absolute line
-					renderCtx.state._edt = `${BODY_PAD}${theme.fg("muted", "rendering diff…")}`;
-					const dc = resolveDiffColors(theme);
-					const diff = parseDiff(
-						d.oldContent as string,
-						d.newContent as string,
-						3,
-						d.editLine as number,
-					);
-					renderSplit(diff, d.language as string | undefined, MAX_RENDER_LINES, dc)
-						.then((rendered) => {
-							if (renderCtx.state._edk !== key) return;
-							renderCtx.state._edt = rendered;
-							renderCtx.invalidate();
-						})
-						.catch(() => {
-							if (renderCtx.state._edk !== key) return;
-							renderCtx.state._edt = `${BODY_PAD}${d.summary}`;
-							renderCtx.invalidate();
-						});
+				return { target: sp(filePath), summary };
+			},
+			body({ d, result, text, theme, ctx: renderCtx }) {
+				// Single edit — full split diff
+				if (d?._type === "editInfo") {
+					const key = `ed:${diffThemeCacheKey(theme)}:${termW()}:${d.summary}:${(d.oldContent as string).length}:${(d.newContent as string).length}:${d.language ?? ""}`;
+					if (renderCtx.toolCallId) trackInvalidator(renderCtx.toolCallId, renderCtx.invalidate);
+					if (renderCtx.state._edk !== key) {
+						renderCtx.state._edk = key;
+						// ponytail: call already shows `edit <file> <summary>`; don't repeat summary+loc header — gutter carries absolute line
+						renderCtx.state._edt = `${BODY_PAD}${theme.fg("muted", "rendering diff…")}`;
+						const dc = resolveDiffColors(theme);
+						const diff = parseDiff(
+							d.oldContent as string,
+							d.newContent as string,
+							3,
+							d.editLine as number,
+						);
+						renderSplit(diff, d.language as string | undefined, MAX_RENDER_LINES, dc)
+							.then((rendered) => {
+								if (renderCtx.state._edk !== key) return;
+								renderCtx.state._edt = rendered;
+								renderCtx.invalidate();
+							})
+							.catch(() => {
+								if (renderCtx.state._edk !== key) return;
+								renderCtx.state._edt = `${BODY_PAD}${d.summary}`;
+								renderCtx.invalidate();
+							});
+					}
+					text.setText(renderCtx.state._edt ?? `${BODY_PAD}${d.summary}`);
+					return undefined;
 				}
-				text.setText(renderCtx.state._edt ?? `${BODY_PAD}${d.summary}`);
-				return isPartial ? text : completed();
-			}
 
-			// Multi-edit — stacked diffs
-			if (d?._type === "multiEditInfo") {
-				const key = `med:${diffThemeCacheKey(theme)}:${termW()}:${d.summary}:${d.editCount}:${d.diffLineCount}`;
-				if (renderCtx.toolCallId) trackInvalidator(renderCtx.toolCallId, renderCtx.invalidate);
-				if (renderCtx.state._edk !== key) {
-					renderCtx.state._edk = key;
-					// ponytail: call already shows summary; render diffs directly
-					renderCtx.state._edt = `${BODY_PAD}${theme.fg("muted", "rendering diff…")}`;
-					const dc = resolveDiffColors(theme);
-					Promise.all(
-						(
-							d.ops as Array<{
-								oldContent: string;
-								newContent: string;
-								language?: string;
-								editLine?: number;
-							}>
-						).map((op) => {
-							const diff = parseDiff(op.oldContent, op.newContent, 3, op.editLine ?? 0);
-							return renderSplit(diff, op.language, MAX_RENDER_LINES, dc);
-						}),
-					)
-						.then((rendered) => {
-							if (renderCtx.state._edk !== key) return;
-							const body = rendered.join(`\n${`${BODY_PAD}${theme.fg("muted", "···")}`}\n`);
-							renderCtx.state._edt = body;
-							renderCtx.invalidate();
-						})
-						.catch(() => {
-							if (renderCtx.state._edk !== key) return;
-							renderCtx.state._edt = `${BODY_PAD}${d.editCount} edits ${d.summary}`;
-							renderCtx.invalidate();
-						});
+				// Multi-edit — stacked diffs
+				if (d?._type === "multiEditInfo") {
+					const key = `med:${diffThemeCacheKey(theme)}:${termW()}:${d.summary}:${d.editCount}:${d.diffLineCount}`;
+					if (renderCtx.toolCallId) trackInvalidator(renderCtx.toolCallId, renderCtx.invalidate);
+					if (renderCtx.state._edk !== key) {
+						renderCtx.state._edk = key;
+						// ponytail: call already shows summary; render diffs directly
+						renderCtx.state._edt = `${BODY_PAD}${theme.fg("muted", "rendering diff…")}`;
+						const dc = resolveDiffColors(theme);
+						Promise.all(
+							(
+								d.ops as Array<{
+									oldContent: string;
+									newContent: string;
+									language?: string;
+									editLine?: number;
+								}>
+							).map((op) => {
+								const diff = parseDiff(op.oldContent, op.newContent, 3, op.editLine ?? 0);
+								return renderSplit(diff, op.language, MAX_RENDER_LINES, dc);
+							}),
+						)
+							.then((rendered) => {
+								if (renderCtx.state._edk !== key) return;
+								const body = rendered.join(`\n${`${BODY_PAD}${theme.fg("muted", "···")}`}\n`);
+								renderCtx.state._edt = body;
+								renderCtx.invalidate();
+							})
+							.catch(() => {
+								if (renderCtx.state._edk !== key) return;
+								renderCtx.state._edt = `${BODY_PAD}${d.editCount} edits ${d.summary}`;
+								renderCtx.invalidate();
+							});
+					}
+					text.setText(renderCtx.state._edt ?? `${BODY_PAD}${d.editCount} edits ${d.summary}`);
+					return undefined;
 				}
-				text.setText(renderCtx.state._edt ?? `${BODY_PAD}${d.editCount} edits ${d.summary}`);
-				return isPartial ? text : completed();
-			}
 
-			const fallback = result.content?.[0];
-			const fallbackText = fallback && isTextContent(fallback) ? fallback.text : "edited";
-			text.setText(
-				fillToolBackground(`${BODY_PAD}${theme.fg("dim", String(fallbackText).slice(0, 120))}`),
-			);
-			return isPartial ? text : completed();
-		},
+				const fallback = result.content?.[0];
+				const fallbackText = fallback && isTextContent(fallback) ? fallback.text : "edited";
+				text.setText(
+					fillToolBackground(`${BODY_PAD}${theme.fg("dim", String(fallbackText).slice(0, 120))}`),
+				);
+				return undefined;
+			},
+		}),
 	});
 }

package/src/extension.ts

@@ -1,25 +1,21 @@
-import {
-	createEditToolDefinition,
-	createEditTool as createEditToolFallback,
-	type EditToolInput,
-	type ExtensionAPI,
-} from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
 import { CursorStore, fffState } from "@xynogen/pix-pretty/fff";
 import { attachResizeListener, trackInvalidator } from "@xynogen/pix-pretty/resize";
-import type { PiPrettyApi, ToolFactory } from "@xynogen/pix-pretty/types";
+import { Text } from "@xynogen/pix-pretty/tui";
 import { linkedShortPath, viewportTextConstructor } from "@xynogen/pix-pretty/utils";
 import { initHashline } from "@xynogen/pix-runtime/hashline";
+import {
+	createEditToolDefinition,
+	createEditTool as createEditToolFallback,
+	type ExtensionAPI,
+} from "@xynogen/pix-runtime/host";
 import { once } from "@xynogen/pix-runtime/once";
 import { homeDir } from "@xynogen/pix-runtime/paths";
 import { registerEditTool } from "./edit.ts";
 
 export default async function pixEditExtension(pi: ExtensionAPI): Promise<void> {
 	await initHashline();
-	const prettyPi = pi as unknown as PiPrettyApi;
 	once(pi, "pix-edit", () => {
-		const createEditTool = (createEditToolDefinition ??
-			createEditToolFallback) as unknown as ToolFactory<EditToolInput>;
+		const createEditTool = createEditToolDefinition ?? createEditToolFallback;
 		if (!createEditTool) return;
 
 		const cwd = process.cwd();
@@ -28,7 +24,7 @@ export default async function pixEditExtension(pi: ExtensionAPI): Promise<void>
 		attachResizeListener();
 
 		registerEditTool(
-			prettyPi,
+			pi,
 			createEditTool,
 			{
 				cwd,