pi-rtk-optimizer 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.5] - 2026-04-24
+
+### Changed
+- Config path resolution now uses Pi's `getAgentDir()` API so `PI_CODING_AGENT_DIR` is respected for extension config paths (thanks to @tynanbe for PR #3).
+- Global skill-read preservation paths now resolve through Pi's agent directory so `PI_CODING_AGENT_DIR` is respected (thanks to @tynanbe for PR #3).
+- Source-filter troubleshooting note injection now only runs when output compaction, source filtering, and read truncation safeguards are active (thanks to @philipbjorge for PR #4).
+- Updated `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` peer dependencies to ^0.70.0.
+- Clarified README and settings modal copy for global extension/config paths, skill directory paths, source-filter note behavior, architecture, and event hooks.
+
+### Removed
+- Removed the unused local asset directory.
+- Removed the `session_switch` event refresh handler.
+
 ## [0.5.3] - 2026-04-01
 
 ### Changed

package/README.md

@@ -59,9 +59,10 @@ Multi-stage pipeline to reduce token consumption:
 
 Place this folder in one of the following locations:
 
-```
-~/.pi/agent/extensions/pi-rtk-optimizer     # Global (all projects)
-.pi/extensions/pi-rtk-optimizer              # Project-specific
+```text
+~/.pi/agent/extensions/pi-rtk-optimizer                 # Global default (when PI_CODING_AGENT_DIR is unset)
+$PI_CODING_AGENT_DIR/extensions/pi-rtk-optimizer        # Global when PI_CODING_AGENT_DIR is set
+.pi/extensions/pi-rtk-optimizer                         # Project-specific
 ```
 
 Pi auto-discovers extensions in these paths on startup.
@@ -107,8 +108,9 @@ Use arrow keys to navigate settings, Enter to cycle values, and Escape to close.
 
 Configuration is stored at:
 
-```
-~/.pi/agent/extensions/pi-rtk-optimizer/config.json
+```text
+Default global path: ~/.pi/agent/extensions/pi-rtk-optimizer/config.json
+Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-rtk-optimizer/config.json when PI_CODING_AGENT_DIR is set
 ```
 
 A starter template is included at `config/config.example.json`.
@@ -145,7 +147,7 @@ A starter template is included at `config/config.example.json`.
 | `outputCompaction.enabled` | boolean | `true` | Enable output compaction pipeline |
 | `outputCompaction.stripAnsi` | boolean | `true` | Remove ANSI escape codes |
 | `outputCompaction.sourceCodeFilteringEnabled` | boolean | `true` | Enable source code filtering for `read` output |
-| `outputCompaction.preserveExactSkillReads` | boolean | `false` | Keep reads under Pi skill directories exact, bypassing read compaction |
+| `outputCompaction.preserveExactSkillReads` | boolean | `false` | Keep reads under configured Pi/global/project skill directories exact, bypassing read compaction |
 | `outputCompaction.sourceCodeFiltering` | string | `"minimal"` | Filter level: `"none"`, `"minimal"`, `"aggressive"` |
 | `outputCompaction.aggregateTestOutput` | boolean | `true` | Summarize test runner output |
 | `outputCompaction.filterBuildOutput` | boolean | `true` | Filter build/compile output |
@@ -154,6 +156,8 @@ A starter template is included at `config/config.example.json`.
 | `outputCompaction.groupSearchOutput` | boolean | `true` | Group search results by file |
 | `outputCompaction.trackSavings` | boolean | `true` | Track compaction metrics |
 
+Skill-read preservation covers the global Pi skills directory (`~/.pi/agent/skills` by default, or `$PI_CODING_AGENT_DIR/skills` when set), `~/.agents/skills`, project `.pi/skills`, and ancestor `.agents/skills` directories.
+
 #### Truncation Settings
 
 | Option | Type | Default | Range | Description |
@@ -171,7 +175,7 @@ A starter template is included at `config/config.example.json`.
 | `minimal` | Removes non-doc comments, collapses blank lines |
 | `aggressive` | Also removes imports, keeps only signatures and key logic |
 
-> **Note:** If file edits fail because "old text does not match," disable source filtering via `/rtk`, re-read the file, apply the edit, then re-enable filtering.
+> **Note:** When source filtering and read truncation safeguards are active, Pi injects a troubleshooting note for repeated file-edit mismatches. If edits fail because "old text does not match," disable source filtering via `/rtk`, re-read the file, apply the edit, then re-enable filtering.
 
 ### Example Configuration
 
@@ -224,15 +228,19 @@ src/
 ├── index.ts                # Extension bootstrap and event wiring
 ├── config-store.ts         # Config load/save with normalization
 ├── config-modal.ts         # TUI settings modal and /rtk handler
-├── command-rewriter.ts     # Command tokenization and rewrite logic
-├── rewrite-bypass.ts       # Rewrite safety bypass rules for interactive/structured commands
-├── rewrite-rules.ts        # Rewrite rule catalog
-├── runtime-guard.ts        # Runtime availability guard helpers for rewrite mode
-├── output-compactor.ts     # Tool result compaction pipeline
-├── output-metrics.ts       # Savings tracking and reporting
-├── command-completions.ts  # /rtk subcommand completions
+├── command-rewriter.ts         # Command tokenization and rewrite logic
+├── rewrite-bypass.ts           # Rewrite safety bypass rules for interactive/structured commands
+├── rewrite-rules.ts            # Rewrite rule catalog
+├── rewrite-pipeline-safety.ts  # Shell-safety fixups for rewritten commands
+├── rtk-command-environment.ts  # RTK_DB_PATH scoping for rewritten commands
+├── shell-env-prefix.ts         # Environment assignment parsing helpers
+├── runtime-guard.ts            # Runtime availability guard helpers for rewrite mode
+├── output-compactor.ts         # Tool result compaction pipeline
+├── output-metrics.ts           # Savings tracking and reporting
+├── tool-execution-sanitizer.ts # Streaming bash execution output sanitizer
+├── command-completions.ts      # /rtk subcommand completions
 ├── windows-command-helpers.ts  # Windows bash compatibility
-└── techniques/             # Compaction technique implementations
+└── techniques/                 # Compaction technique implementations
     ├── ansi.ts             # ANSI code stripping
     ├── build.ts            # Build output filtering
     ├── test-output.ts      # Test output aggregation
@@ -247,9 +255,12 @@ src/
 
 The extension hooks into Pi's event system:
 
-- **`beforeToolCall`** — Rewrites bash commands to rtk equivalents
-- **`afterToolResult`** — Compacts tool output before context consumption
-- **`command`** — Handles `/rtk` command and subcommands
+- **`tool_call`** — Rewrites bash commands to rtk equivalents or emits suggestions
+- **`tool_result`** — Compacts completed tool output before context consumption
+- **`tool_execution_start` / `tool_execution_update` / `tool_execution_end`** — Tracks and sanitizes streamed bash output
+- **`before_agent_start`** — Conditionally injects source-filter troubleshooting guidance
+- **`session_start` / `agent_end`** — Refreshes config and clears in-session tracking state
+- **Registered `/rtk` command** — Handles settings, status, verification, stats, and reset subcommands
 
 ### Windows Compatibility
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-rtk-optimizer",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Pi extension that optimizes RTK command rewriting and tool output compaction for the coding agent.",
   "type": "module",
   "main": "./index.ts",
@@ -58,7 +58,7 @@
     ]
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.64.0",
-    "@mariozechner/pi-tui": "^0.64.0"
+    "@mariozechner/pi-coding-agent": "^0.70.0",
+    "@mariozechner/pi-tui": "^0.70.0"
   }
 }

package/src/additional-coverage-test.ts

@@ -1,13 +1,7 @@
 import assert from "node:assert/strict";
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { mock } from "bun:test";
 
-import {
-	ensureConfigExists,
-	getRtkIntegrationConfigPath,
-	loadRtkIntegrationConfig,
-	normalizeRtkIntegrationConfig,
-	saveRtkIntegrationConfig,
-} from "./config-store.ts";
 import { clearOutputMetrics, getOutputMetricsSummary, trackOutputSavings } from "./output-metrics.ts";
 import { runTest } from "./test-helpers.ts";
 import { matchesCommandPatterns, normalizeCommandForDetection } from "./techniques/command-detection.ts";
@@ -19,6 +13,18 @@ import { sanitizeStreamingBashExecutionResult } from "./tool-execution-sanitizer
 import { sanitizeRtkEmojiOutput } from "./techniques/emoji.ts";
 import { stripRtkHookWarnings } from "./techniques/rtk.ts";
 
+mock.module("@mariozechner/pi-coding-agent", () => ({
+	getAgentDir: () => "/tmp/.pi/agent",
+}));
+
+const {
+	ensureConfigExists,
+	getRtkIntegrationConfigPath,
+	loadRtkIntegrationConfig,
+	normalizeRtkIntegrationConfig,
+	saveRtkIntegrationConfig,
+} = await import("./config-store.ts");
+
 function makeTempConfigPath(): string {
 	return `${getRtkIntegrationConfigPath()}.test-${Date.now()}-${Math.random().toString(16).slice(2)}.json`;
 }

package/src/config-modal-test.ts

@@ -4,6 +4,7 @@ import { mock } from "bun:test";
 import { cloneDefaultConfig, runTest } from "./test-helpers.ts";
 
 mock.module("@mariozechner/pi-coding-agent", () => ({
+	getAgentDir: () => "/tmp/.pi/agent",
 	getSettingsListTheme: () => ({}),
 }));
 

package/src/config-modal.ts

@@ -143,7 +143,7 @@ function buildSettingItems(config: RtkIntegrationConfig): SettingItem[] {
 		{
 			id: "outputPreserveExactSkillReads",
 			label: "Preserve exact skill reads",
-			description: "If on, read results under ~/.pi/agent/skills, ~/.agents/skills, .pi/skills, and ancestor .agents/skills skip read compaction",
+			description: "If on, read results under the global Pi skills directory (default: ~/.pi/agent/skills, respects PI_CODING_AGENT_DIR), ~/.agents/skills, .pi/skills, and ancestor .agents/skills skip read compaction",
 			currentValue: toOnOff(config.outputCompaction.preserveExactSkillReads),
 			values: ON_OFF,
 		},

package/src/constants.ts

@@ -1,6 +1,6 @@
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-export const EXTENSION_NAME = "pi-rtk-optimizer";
-export const CONFIG_DIR = join(homedir(), ".pi", "agent", "extensions", EXTENSION_NAME);
-export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { join } from "node:path";
+
+export const EXTENSION_NAME = "pi-rtk-optimizer";
+export const CONFIG_DIR = join(getAgentDir(), "extensions", EXTENSION_NAME);
+export const CONFIG_PATH = join(CONFIG_DIR, "config.json");

package/src/index-test.ts

@@ -4,6 +4,7 @@ import { mock } from "bun:test";
 import { runTest } from "./test-helpers.ts";
 
 mock.module("@mariozechner/pi-coding-agent", () => ({
+	getAgentDir: () => "/tmp/.pi/agent",
 	getSettingsListTheme: () => ({}),
 	isToolCallEventType: (toolName: string, event: Record<string, unknown>) => event.toolName === toolName,
 }));
@@ -27,7 +28,38 @@ mock.module("@mariozechner/pi-tui", () => ({
 	visibleWidth: (text: string) => text.length,
 }));
 
-const { createBoundedNoticeTracker } = await import("./index.ts");
+const { createBoundedNoticeTracker, shouldInjectSourceFilterTroubleshootingNote } = await import("./index.ts");
+const { DEFAULT_RTK_INTEGRATION_CONFIG } = await import("./types.ts");
+
+function configWith(overrides: {
+	enabled?: boolean;
+	compactionEnabled?: boolean;
+	sourceFilteringEnabled?: boolean;
+	sourceFilteringLevel?: "none" | "minimal" | "aggressive";
+	smartTruncateEnabled?: boolean;
+	truncateEnabled?: boolean;
+}): typeof DEFAULT_RTK_INTEGRATION_CONFIG {
+	const base = DEFAULT_RTK_INTEGRATION_CONFIG;
+	return {
+		...base,
+		enabled: overrides.enabled ?? base.enabled,
+		outputCompaction: {
+			...base.outputCompaction,
+			enabled: overrides.compactionEnabled ?? base.outputCompaction.enabled,
+			sourceCodeFilteringEnabled:
+				overrides.sourceFilteringEnabled ?? base.outputCompaction.sourceCodeFilteringEnabled,
+			sourceCodeFiltering: overrides.sourceFilteringLevel ?? base.outputCompaction.sourceCodeFiltering,
+			smartTruncate: {
+				...base.outputCompaction.smartTruncate,
+				enabled: overrides.smartTruncateEnabled ?? base.outputCompaction.smartTruncate.enabled,
+			},
+			truncate: {
+				...base.outputCompaction.truncate,
+				enabled: overrides.truncateEnabled ?? base.outputCompaction.truncate.enabled,
+			},
+		},
+	};
+}
 
 runTest("bounded notice tracker evicts old entries and supports reset", () => {
 	const tracker = createBoundedNoticeTracker(2);
@@ -51,4 +83,52 @@ runTest("bounded notice tracker coerces invalid limits to a safe minimum", () =>
 	assert.equal(tracker.remember("alpha"), true);
 });
 
+runTest("source-filter note injected when source filtering is active", () => {
+	assert.equal(
+		shouldInjectSourceFilterTroubleshootingNote(
+			configWith({ sourceFilteringEnabled: true, sourceFilteringLevel: "minimal" }),
+		),
+		true,
+	);
+	assert.equal(
+		shouldInjectSourceFilterTroubleshootingNote(
+			configWith({ sourceFilteringEnabled: true, sourceFilteringLevel: "aggressive" }),
+		),
+		true,
+	);
+});
+
+runTest("source-filter note skipped when extension is disabled", () => {
+	assert.equal(shouldInjectSourceFilterTroubleshootingNote(configWith({ enabled: false })), false);
+});
+
+runTest("source-filter note skipped when compaction is disabled", () => {
+	assert.equal(shouldInjectSourceFilterTroubleshootingNote(configWith({ compactionEnabled: false })), false);
+});
+
+runTest("source-filter note skipped when source filtering flag is off", () => {
+	assert.equal(
+		shouldInjectSourceFilterTroubleshootingNote(configWith({ sourceFilteringEnabled: false })),
+		false,
+	);
+});
+
+runTest("source-filter note skipped when filtering level is 'none'", () => {
+	assert.equal(
+		shouldInjectSourceFilterTroubleshootingNote(
+			configWith({ sourceFilteringEnabled: true, sourceFilteringLevel: "none" }),
+		),
+		false,
+	);
+});
+
+runTest("source-filter note skipped when all read filtering safeguards are disabled", () => {
+	assert.equal(
+		shouldInjectSourceFilterTroubleshootingNote(
+			configWith({ smartTruncateEnabled: false, truncateEnabled: false }),
+		),
+		false,
+	);
+});
+
 console.log("All index tests passed.");

package/src/index.ts

@@ -30,6 +30,17 @@ function trimMessage(raw: string, maxLength = 220): string {
 const SOURCE_FILTER_TROUBLESHOOTING_NOTE =
 	"RTK note: If file edits repeatedly fail because old text does not match, ask the user to manually run '/rtk' in the Pi TUI, disable 'Read source filtering enabled', re-read the file, apply the edit, then ask the user to manually re-enable it in the Pi TUI.";
 
+export function shouldInjectSourceFilterTroubleshootingNote(config: RtkIntegrationConfig): boolean {
+	const compaction = config.outputCompaction;
+	return (
+		config.enabled &&
+		compaction.enabled &&
+		compaction.sourceCodeFilteringEnabled &&
+		compaction.sourceCodeFiltering !== "none" &&
+		(compaction.smartTruncate.enabled || compaction.truncate.enabled)
+	);
+}
+
 function mergeCompactionDetails(
 	existingDetails: unknown,
 	compaction: ToolResultCompactionMetadata,
@@ -262,14 +273,6 @@ export default function rtkIntegrationExtension(pi: ExtensionAPI): void {
 		maybeWarnRtkMissing(ctx);
 	});
 
-	pi.on("session_switch", async (_event, ctx) => {
-		warnedMessages.reset();
-		suggestionNotices.reset();
-		clearTrackedBashCommands();
-		missingRtkWarningShown = false;
-		await refreshConfig(ctx);
-		maybeWarnRtkMissing(ctx);
-	});
 
 	pi.on("agent_end", async () => {
 		clearTrackedBashCommands();
@@ -324,6 +327,10 @@ export default function rtkIntegrationExtension(pi: ExtensionAPI): void {
 		await ensureRuntimeStatusFresh();
 		maybeWarnRtkMissing(ctx);
 
+		if (!shouldInjectSourceFilterTroubleshootingNote(config)) {
+			return {};
+		}
+
 		if (event.systemPrompt.includes(SOURCE_FILTER_TROUBLESHOOTING_NOTE)) {
 			return {};
 		}

package/src/output-compactor-test.ts

@@ -1,10 +1,17 @@
 import assert from "node:assert/strict";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { mock } from "bun:test";
 
-import { compactToolResult } from "./output-compactor.ts";
 import { cloneDefaultConfig, runTest } from "./test-helpers.ts";
 
+const TEST_AGENT_DIR = "/tmp/.pi/agent";
+
+mock.module("@mariozechner/pi-coding-agent", () => ({
+	getAgentDir: () => TEST_AGENT_DIR,
+}));
+
+const { compactToolResult } = await import("./output-compactor.ts");
+
 function buildReadContent(lineCount: number): string {
 	const lines: string[] = [];
 	for (let index = 0; index < lineCount; index += 1) {
@@ -216,7 +223,7 @@ runTest("skill reads stay exact when preserveExactSkillReads is enabled for user
 	const result = compactToolResult(
 		{
 			toolName: "read",
-			input: { path: join(homedir(), ".pi", "agent", "skills", "example", "SKILL.md") },
+			input: { path: join(TEST_AGENT_DIR, "skills", "example", "SKILL.md") },
 			content: [{ type: "text", text: content }],
 		},
 		config,

package/src/output-compactor.ts

@@ -1,3 +1,4 @@
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
 import { homedir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
 import {
@@ -60,7 +61,7 @@ const LOSSY_TECHNIQUE_PREFIXES = [
 
 const READ_EXACT_OUTPUT_LINE_THRESHOLD = 80;
 const READ_COMPACTION_BANNER_PREFIX = "[RTK compacted output:";
-const USER_SKILL_ROOTS = [join(homedir(), ".pi", "agent", "skills"), join(homedir(), ".agents", "skills")];
+const USER_SKILL_ROOTS = [join(getAgentDir(), "skills"), join(homedir(), ".agents", "skills")];
 
 function normalizePathForComparison(path: string): string {
 	return process.platform === "win32" ? path.toLowerCase() : path;

package/src/types-shims.d.ts

@@ -89,6 +89,7 @@ declare module "@mariozechner/pi-coding-agent" {
 		getFgAnsi?(name: string): string;
 	}
 
+	export function getAgentDir(): string;
 	export function getSettingsListTheme(): unknown;
 
 	export interface ExtensionAPI {