pi-formatter 0.3.0 → 1.0.0

package/README.md

@@ -3,9 +3,11 @@
 A [pi](https://pi.dev) extension that auto-formats files after `write` and
 `edit` tool calls.
 
-By default, formatting runs after each successful tool result. It can also be
-configured to defer formatting until the agent stops and yields back to the
-user.
+By default, formatting runs once per turn. You can also format after each tool
+call or defer formatting until the current session shuts down.
+
+This default changed from the previous immediate-per-tool behavior. If you want
+the old default, set `"formatMode": "tool"`.
 
 ## 📦 Install
 
@@ -20,13 +22,19 @@ best-effort post-processing. Formatter failures never block tool results.
 
 Formatting modes:
 
-- `afterEachToolCall`: format immediately after each successful `write` or
-  `edit` tool result. This is the default.
-- `afterAgentStop`: collect touched files during the run and format them once
-  the agent stops. This avoids mid-run model drift from formatter edits.
-
-When `afterAgentStop` is active, interrupted or canceled runs are not formatted
-unless `formatOnAbort` is enabled.
+- `tool`: format immediately after each successful `write` or `edit` tool
+  result.
+  Use this mode when you want the file on disk to stay formatted after every
+  edit, even while the agent is still working.
+- `turn`: collect files touched during the current turn and format them once at
+  `turn_end`. This is the default.
+  Use this mode when you want to avoid mid-turn formatter drift while still
+  keeping files formatted throughout the run.
+- `session`: collect files touched during the current session and format them
+  once at `session_shutdown`.
+  Use this mode when you want the fewest formatter interruptions and are okay
+  with formatting only when the session exits, reloads, or switches. Interrupted
+  runs stay pending until the session ends or changes.
 
 Supported file types:
 
@@ -53,17 +61,14 @@ folder (default: `~/.pi/agent`, overridable via `PI_CODING_AGENT_DIR`):
 
 ```json
 {
-  "formatMode": "afterEachToolCall",
-  "formatOnAbort": false,
+  "formatMode": "turn",
   "commandTimeoutMs": 10000,
   "hideCallSummariesInTui": false
 }
 ```
 
-- `formatMode`: formatting strategy
-  (`"afterEachToolCall"` | `"afterAgentStop"`, default: `"afterEachToolCall"`)
-- `formatOnAbort`: in deferred mode, also format files after an interrupted or
-  canceled run (default: `false`)
+- `formatMode`: formatting strategy (`"tool"` | `"turn"` | `"session"`,
+  default: `"turn"`). Use `"tool"` to restore the old immediate default.
 - `commandTimeoutMs`: timeout (ms) per formatter command (default: `10000`)
 - `hideCallSummariesInTui`: hide formatter pass/fail summaries in the TUI
   (default: `false`)

package/extensions/formatter/config.ts

@@ -1,32 +1,24 @@
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@mariozechner/pi-coding-agent";
 
-export type FormatMode = "afterEachToolCall" | "afterAgentStop";
+export type FormatMode = "tool" | "turn" | "session";
 
 const DEFAULT_COMMAND_TIMEOUT_MS = 10_000;
 const DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI = false;
-const DEFAULT_FORMAT_MODE: FormatMode = "afterEachToolCall";
-const DEFAULT_FORMAT_ON_ABORT = false;
+const DEFAULT_FORMAT_MODE: FormatMode = "turn";
 const FORMATTER_CONFIG_FILE = "formatter.json";
 
 export type FormatterConfigSnapshot = {
   commandTimeoutMs: number;
   hideCallSummariesInTui: boolean;
   formatMode: FormatMode;
-  formatOnAbort: boolean;
 };
 
 export const DEFAULT_FORMATTER_CONFIG: FormatterConfigSnapshot = {
   commandTimeoutMs: DEFAULT_COMMAND_TIMEOUT_MS,
   hideCallSummariesInTui: DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI,
   formatMode: DEFAULT_FORMAT_MODE,
-  formatOnAbort: DEFAULT_FORMAT_ON_ABORT,
 };
 
 export function getFormatterConfigPath(): string {
@@ -73,7 +65,7 @@ function parseBooleanValue(value: unknown, defaultValue: boolean): boolean {
 }
 
 function parseFormatMode(value: unknown, defaultValue: FormatMode): FormatMode {
-  if (value === "afterEachToolCall" || value === "afterAgentStop") {
+  if (value === "tool" || value === "turn" || value === "session") {
     return value;
   }
 
@@ -87,7 +79,6 @@ function toFormatterConfigObject(
     commandTimeoutMs: config.commandTimeoutMs,
     hideCallSummariesInTui: config.hideCallSummariesInTui,
     formatMode: config.formatMode,
-    formatOnAbort: config.formatOnAbort,
   };
 }
 
@@ -113,10 +104,6 @@ export function loadFormatterConfig(): FormatterConfigSnapshot {
       DEFAULT_HIDE_CALL_SUMMARIES_IN_TUI,
     ),
     formatMode: parseFormatMode(config.formatMode, DEFAULT_FORMAT_MODE),
-    formatOnAbort: parseBooleanValue(
-      config.formatOnAbort,
-      DEFAULT_FORMAT_ON_ABORT,
-    ),
   };
 }
 
@@ -127,7 +114,6 @@ export function cloneFormatterConfig(
     commandTimeoutMs: config.commandTimeoutMs,
     hideCallSummariesInTui: config.hideCallSummariesInTui,
     formatMode: config.formatMode,
-    formatOnAbort: config.formatOnAbort,
   };
 }
 

package/extensions/formatter/context.ts

@@ -1,7 +1,11 @@
 import { readdir, readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { getPathForGit, isWithinDirectory, pathExists } from "./path.js";
+import {
+  getRelativePathOrAbsolute,
+  isWithinDirectory,
+  pathExists,
+} from "./path.js";
 import { hasCommand } from "./system.js";
 import type { FileKind, RequiredMajorVersion, RunnerContext } from "./types.js";
 
@@ -239,12 +243,12 @@ export class FormatRunContext implements RunnerContext {
   }
 
   private async resolveChangedLines(): Promise<string[]> {
-    const gitPath = getPathForGit(this.filePath, this.cwd);
+    const diffPath = getRelativePathOrAbsolute(this.filePath, this.cwd);
     const rangeSet = new Set<string>();
 
     const diffArgSets = [
-      ["diff", "--unified=0", "--", gitPath],
-      ["diff", "--cached", "--unified=0", "--", gitPath],
+      ["diff", "--unified=0", "--", diffPath],
+      ["diff", "--cached", "--unified=0", "--", diffPath],
     ];
 
     for (const args of diffArgSets) {

package/extensions/formatter/path.ts

@@ -54,8 +54,11 @@ export function isWithinDirectory(
   );
 }
 
-export function getPathForGit(filePath: string, cwd: string): string {
-  const relPath = relative(cwd, filePath);
+export function getRelativePathOrAbsolute(
+  filePath: string,
+  directory: string,
+): string {
+  const relPath = relative(directory, filePath);
   if (
     !relPath ||
     relPath === "." ||

package/extensions/index.ts

@@ -1,11 +1,15 @@
-import { basename } from "node:path";
 import {
   type ExtensionAPI,
   getSettingsListTheme,
   isEditToolResult,
   isWriteToolResult,
 } from "@mariozechner/pi-coding-agent";
-import { Container, type SettingItem, SettingsList, Text } from "@mariozechner/pi-tui";
+import {
+  Container,
+  type SettingItem,
+  SettingsList,
+  Text,
+} from "@mariozechner/pi-tui";
 import {
   cloneFormatterConfig,
   type FormatterConfigSnapshot,
@@ -15,36 +19,39 @@ import {
 } from "./formatter/config.js";
 import { type FormatCallSummary, formatFile } from "./formatter/dispatch.js";
 import {
-  getPathForGit,
+  getRelativePathOrAbsolute,
   pathExists,
   resolveToolPath,
 } from "./formatter/path.js";
 
+function normalizeSummaryMessage(message: string): string {
+  return message.replace(/\s+/g, " ").trim();
+}
+
 function formatError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
-function formatSummaryPath(filePath: string, cwd: string): string {
-  const pathForDisplay = getPathForGit(filePath, cwd);
-  return pathForDisplay.startsWith("/")
-    ? basename(pathForDisplay)
-    : pathForDisplay;
-}
+function formatCallSummary(
+  summary: FormatCallSummary,
+  fileLabel: string,
+): string {
+  const prefix = summary.status === "succeeded" ? "✔︎" : "✘";
+  const base = `${prefix} ${summary.runnerId}: ${fileLabel}`;
 
-function formatCallSuccessSummary(summary: FormatCallSummary): string {
-  return `✔︎ ${summary.runnerId}`;
-}
+  if (summary.status === "succeeded") {
+    return base;
+  }
 
-function formatCallFailureSummary(summary: FormatCallSummary): string {
   if (summary.failureMessage) {
-    return `✘ ${summary.runnerId}: ${summary.failureMessage}`;
+    return `${base}: ${normalizeSummaryMessage(summary.failureMessage)}`;
   }
 
   if (summary.exitCode !== undefined) {
-    return `✘ ${summary.runnerId} (exit ${summary.exitCode})`;
+    return `${base} (exit ${summary.exitCode})`;
   }
 
-  return `✘ ${summary.runnerId}`;
+  return base;
 }
 
 function resolveEventPath(rawPath: unknown, cwd: string): string | undefined {
@@ -72,17 +79,9 @@ function getFormatterSettingItems(
       id: "formatMode",
       label: "Format mode",
       description:
-        "Choose whether formatting runs after each successful write/edit tool call or once after the agent stops.",
+        "Choose whether formatting runs after each successful write/edit tool call, once after each turn, or once when the session shuts down.",
       currentValue: config.formatMode,
-      values: ["afterEachToolCall", "afterAgentStop"],
-    },
-    {
-      id: "formatOnAbort",
-      label: "Format on abort",
-      description:
-        "When enabled, deferred formatting also runs if the model is interrupted or cancelled.",
-      currentValue: config.formatOnAbort ? "on" : "off",
-      values: ["off", "on"],
+      values: ["tool", "turn", "session"],
     },
     {
       id: "commandTimeoutMs",
@@ -102,11 +101,19 @@ function getFormatterSettingItems(
   ];
 }
 
+type FormatterContext = {
+  cwd: string;
+  hasUI: boolean;
+  ui: {
+    notify(message: string, level: "info" | "warning" | "error"): void;
+  };
+};
+
 export default function (pi: ExtensionAPI) {
   let formatterConfig = loadFormatterConfig();
   const formatQueueByPath = new Map<string, Promise<void>>();
-  const candidatePaths = new Set<string>();
-  const successfulPaths = new Set<string>();
+  const pendingTurnPaths = new Set<string>();
+  const pendingSessionPaths = new Set<string>();
 
   const enqueueFormat = async (
     filePath: string,
@@ -130,13 +137,7 @@ export default function (pi: ExtensionAPI) {
 
   const formatResolvedPath = async (
     filePath: string,
-    ctx: {
-      cwd: string;
-      hasUI: boolean;
-      ui: {
-        notify(message: string, level: "info" | "warning" | "error"): void;
-      };
-    },
+    ctx: FormatterContext,
   ): Promise<void> => {
     if (!(await pathExists(filePath))) {
       return;
@@ -144,7 +145,7 @@ export default function (pi: ExtensionAPI) {
 
     const showSummaries = !formatterConfig.hideCallSummariesInTui && ctx.hasUI;
     const notifyWarning = (message: string) => {
-      const normalizedMessage = message.replace(/\s+/g, " ").trim();
+      const normalizedMessage = normalizeSummaryMessage(message);
 
       if (ctx.hasUI) {
         ctx.ui.notify(normalizedMessage, "warning");
@@ -162,12 +163,11 @@ export default function (pi: ExtensionAPI) {
           }
         : undefined;
 
-      const runnerWarningReporter =
-        showSummaries && ctx.hasUI
-          ? () => {
-              // Summary mode already reports failures compactly.
-            }
-          : notifyWarning;
+      const runnerWarningReporter = showSummaries
+        ? () => {
+            // Summary mode already reports failures compactly.
+          }
+        : notifyWarning;
 
       try {
         await formatFile(
@@ -179,7 +179,7 @@ export default function (pi: ExtensionAPI) {
           runnerWarningReporter,
         );
       } catch (error) {
-        const fileLabel = formatSummaryPath(filePath, ctx.cwd);
+        const fileLabel = getRelativePathOrAbsolute(filePath, ctx.cwd);
         notifyWarning(`Failed to format ${fileLabel}: ${formatError(error)}`);
       }
 
@@ -187,102 +187,92 @@ export default function (pi: ExtensionAPI) {
         return;
       }
 
-      for (const summary of summaries) {
-        if (summary.status === "succeeded") {
-          ctx.ui.notify(formatCallSuccessSummary(summary), "info");
-          continue;
-        }
+      const fileLabel = getRelativePathOrAbsolute(filePath, ctx.cwd);
 
-        ctx.ui.notify(formatCallFailureSummary(summary), "info");
+      for (const summary of summaries) {
+        ctx.ui.notify(formatCallSummary(summary, fileLabel), "info");
       }
     });
   };
 
+  const flushPaths = async (
+    paths: Set<string>,
+    ctx: FormatterContext,
+  ): Promise<void> => {
+    const batch = [...paths];
+    paths.clear();
+
+    for (const filePath of batch) {
+      await formatResolvedPath(filePath, ctx);
+    }
+  };
+
+  const flushPendingPaths = async (ctx: FormatterContext): Promise<void> => {
+    await flushPaths(pendingTurnPaths, ctx);
+    await flushPaths(pendingSessionPaths, ctx);
+  };
+
   const reloadFormatterConfig = () => {
     formatterConfig = loadFormatterConfig();
   };
 
-  pi.on("agent_start", async () => {
-    candidatePaths.clear();
-    successfulPaths.clear();
-  });
-
-  pi.on("tool_call", async (event, ctx) => {
-    if (formatterConfig.formatMode !== "afterAgentStop") {
+  pi.on("tool_result", async (event, ctx) => {
+    if (!isWriteToolResult(event) && !isEditToolResult(event)) {
       return;
     }
 
-    if (event.toolName !== "write" && event.toolName !== "edit") {
+    if (event.isError) {
       return;
     }
 
     const filePath = resolveEventPath(event.input.path, ctx.cwd);
-    if (filePath) {
-      candidatePaths.add(filePath);
+    if (!filePath) {
+      return;
     }
-  });
 
-  pi.on("tool_result", async (event, ctx) => {
-    if (!isWriteToolResult(event) && !isEditToolResult(event)) {
+    if (formatterConfig.formatMode === "tool") {
+      await formatResolvedPath(filePath, ctx);
       return;
     }
 
-    const filePath = resolveEventPath(event.input.path, ctx.cwd);
-    if (!filePath) {
+    if (formatterConfig.formatMode === "turn") {
+      pendingTurnPaths.add(filePath);
       return;
     }
 
-    if (!event.isError) {
-      successfulPaths.add(filePath);
-    }
+    pendingSessionPaths.add(filePath);
+  });
 
-    if (formatterConfig.formatMode !== "afterEachToolCall" || event.isError) {
+  pi.on("turn_end", async (_event, ctx) => {
+    if (pendingTurnPaths.size === 0) {
       return;
     }
 
-    await formatResolvedPath(filePath, ctx);
+    await flushPaths(pendingTurnPaths, ctx);
   });
 
-  pi.on("agent_end", async (event, ctx) => {
-    if (formatterConfig.formatMode !== "afterAgentStop") {
-      candidatePaths.clear();
-      successfulPaths.clear();
+  pi.on("agent_end", async (_event, ctx) => {
+    if (pendingTurnPaths.size === 0) {
       return;
     }
 
-    let lastAssistantStopReason: string | undefined;
-    for (let index = event.messages.length - 1; index >= 0; index -= 1) {
-      const message = event.messages[index];
-      if (message.role !== "assistant") {
-        continue;
-      }
-
-      lastAssistantStopReason = message.stopReason;
-      break;
-    }
+    await flushPaths(pendingTurnPaths, ctx);
+  });
 
-    const pathsToFormat = new Set<string>();
-    if (lastAssistantStopReason === "aborted") {
-      if (formatterConfig.formatOnAbort) {
-        for (const filePath of candidatePaths) {
-          pathsToFormat.add(filePath);
-        }
-        for (const filePath of successfulPaths) {
-          pathsToFormat.add(filePath);
-        }
-      }
-    } else {
-      for (const filePath of successfulPaths) {
-        pathsToFormat.add(filePath);
-      }
+  pi.on("session_switch", async (_event, ctx) => {
+    if (pendingTurnPaths.size === 0 && pendingSessionPaths.size === 0) {
+      return;
     }
 
-    candidatePaths.clear();
-    successfulPaths.clear();
+    await flushPendingPaths(ctx);
+  });
 
-    for (const filePath of pathsToFormat) {
-      await formatResolvedPath(filePath, ctx);
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (pendingTurnPaths.size === 0 && pendingSessionPaths.size === 0) {
+      return;
     }
+
+    await flushPendingPaths(ctx);
   });
 
   pi.registerCommand("formatter", {
@@ -307,10 +297,6 @@ export default function (pi: ExtensionAPI) {
 
         const syncDraftToSettingsList = (settingsList: SettingsList) => {
           settingsList.updateValue("formatMode", draft.formatMode);
-          settingsList.updateValue(
-            "formatOnAbort",
-            draft.formatOnAbort ? "on" : "off",
-          );
           settingsList.updateValue(
             "commandTimeoutMs",
             String(draft.commandTimeoutMs),
@@ -329,9 +315,8 @@ export default function (pi: ExtensionAPI) {
             const previous = cloneFormatterConfig(draft);
 
             if (id === "formatMode") {
-              draft.formatMode = newValue as FormatterConfigSnapshot["formatMode"];
-            } else if (id === "formatOnAbort") {
-              draft.formatOnAbort = newValue === "on";
+              draft.formatMode =
+                newValue as FormatterConfigSnapshot["formatMode"];
             } else if (id === "commandTimeoutMs") {
               draft.commandTimeoutMs = Number.parseInt(newValue, 10);
             } else if (id === "hideCallSummariesInTui") {
@@ -341,13 +326,26 @@ export default function (pi: ExtensionAPI) {
             try {
               writeFormatterConfigSnapshot(draft);
               reloadFormatterConfig();
+
+              if (
+                id === "formatMode" &&
+                previous.formatMode !== draft.formatMode
+              ) {
+                void flushPendingPaths(ctx).catch((error) => {
+                  const message =
+                    error instanceof Error ? error.message : String(error);
+                  ctx.ui.notify(
+                    `Failed to flush pending formats: ${message}`,
+                    "error",
+                  );
+                });
+              }
             } catch (error) {
               const message =
                 error instanceof Error ? error.message : String(error);
               draft.commandTimeoutMs = previous.commandTimeoutMs;
               draft.hideCallSummariesInTui = previous.hideCallSummariesInTui;
               draft.formatMode = previous.formatMode;
-              draft.formatOnAbort = previous.formatOnAbort;
               syncDraftToSettingsList(settingsList);
               ctx.ui.notify(`Failed to save config: ${message}`, "error");
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-formatter",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Pi extension that auto-formats files after write/edit tool calls.",
   "type": "module",
   "files": [