pi-rtk-optimizer 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -7,15 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.5.4] - 2026-04-22
-
-### Fixed
-- Respected `PI_CODING_AGENT_DIR` when resolving the global extension config directory and preserved exact skill reads under the configured global Pi skills path.
+## [0.5.5] - 2026-04-24
 
 ### Changed
-- Updated README installation/configuration guidance and the settings modal description to document configurable global Pi paths.
-- Removed session-switch lifecycle reinitialization from the extension runtime.
-- Updated `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` peer dependencies to ^0.68.1.
+- 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
 

package/README.md

@@ -60,8 +60,9 @@ Multi-stage pipeline to reduce token consumption:
 Place this folder in one of the following locations:
 
 ```text
-~/.pi/agent/extensions/pi-rtk-optimizer     # Global default (when PI_CODING_AGENT_DIR is unset)
-.pi/extensions/pi-rtk-optimizer              # Project-specific
+~/.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.
@@ -146,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 |
@@ -155,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 |
@@ -172,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
 
@@ -225,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
@@ -248,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,64 +1,64 @@
-{
-  "name": "pi-rtk-optimizer",
-  "version": "0.5.4",
-  "description": "Pi extension that optimizes RTK command rewriting and tool output compaction for the coding agent.",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "config/config.example.json",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
-    "lint": "npm run build",
-    "typecheck": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json",
-    "test": "bun ./src/output-compactor-test.ts && bun ./src/command-rewriter-test.ts && bun ./src/runtime-guard-test.ts && bun ./src/additional-coverage-test.ts && bun ./src/config-modal-test.ts && bun ./src/index-test.ts",
-    "check": "npm run lint && npm run typecheck && npm run test",
-    "build:check": "bunx esbuild ./index.ts --bundle --platform=node --format=esm --outfile=./.pi-rtk-optimizer-check.mjs --external:@mariozechner/pi-coding-agent --external:@mariozechner/pi-tui && bun -e \"import { unlinkSync } from 'node:fs'; unlinkSync('./.pi-rtk-optimizer-check.mjs');\""
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "pi-coding-agent",
-    "coding-agent",
-    "rtk",
-    "token-optimization",
-    "tool-compaction",
-    "output-compaction",
-    "command-rewrite",
-    "optimization"
-  ],
-  "author": "MasuRii",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MasuRii/pi-rtk-optimizer.git"
-  },
-  "bugs": {
-    "url": "https://github.com/MasuRii/pi-rtk-optimizer/issues"
-  },
-  "homepage": "https://github.com/MasuRii/pi-rtk-optimizer#readme",
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.68.1",
-    "@mariozechner/pi-tui": "^0.68.1"
-  }
-}
+{
+  "name": "pi-rtk-optimizer",
+  "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",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config/config.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "lint": "npm run build",
+    "typecheck": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json",
+    "test": "bun ./src/output-compactor-test.ts && bun ./src/command-rewriter-test.ts && bun ./src/runtime-guard-test.ts && bun ./src/additional-coverage-test.ts && bun ./src/config-modal-test.ts && bun ./src/index-test.ts",
+    "check": "npm run lint && npm run typecheck && npm run test",
+    "build:check": "bunx esbuild ./index.ts --bundle --platform=node --format=esm --outfile=./.pi-rtk-optimizer-check.mjs --external:@mariozechner/pi-coding-agent --external:@mariozechner/pi-tui && bun -e \"import { unlinkSync } from 'node:fs'; unlinkSync('./.pi-rtk-optimizer-check.mjs');\""
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "coding-agent",
+    "rtk",
+    "token-optimization",
+    "tool-compaction",
+    "output-compaction",
+    "command-rewrite",
+    "optimization"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-rtk-optimizer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-rtk-optimizer/issues"
+  },
+  "homepage": "https://github.com/MasuRii/pi-rtk-optimizer#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.70.0",
+    "@mariozechner/pi-tui": "^0.70.0"
+  }
+}

package/src/additional-coverage-test.ts

@@ -1,11 +1,20 @@
 import assert from "node:assert/strict";
-import { mock } from "bun:test";
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { mock } from "bun:test";
 
-const MOCK_AGENT_DIR = "C:/tmp/.pi/agent";
+import { clearOutputMetrics, getOutputMetricsSummary, trackOutputSavings } from "./output-metrics.ts";
+import { runTest } from "./test-helpers.ts";
+import { matchesCommandPatterns, normalizeCommandForDetection } from "./techniques/command-detection.ts";
+import { compactPath } from "./techniques/path-utils.ts";
+import { applyWindowsBashCompatibilityFixes } from "./windows-command-helpers.ts";
+import { applyRewrittenCommandShellSafetyFixups } from "./rewrite-pipeline-safety.ts";
+import { applyRtkCommandEnvironment } from "./rtk-command-environment.ts";
+import { sanitizeStreamingBashExecutionResult } from "./tool-execution-sanitizer.ts";
+import { sanitizeRtkEmojiOutput } from "./techniques/emoji.ts";
+import { stripRtkHookWarnings } from "./techniques/rtk.ts";
 
 mock.module("@mariozechner/pi-coding-agent", () => ({
-	getAgentDir: () => MOCK_AGENT_DIR,
+	getAgentDir: () => "/tmp/.pi/agent",
 }));
 
 const {
@@ -15,16 +24,6 @@ const {
 	normalizeRtkIntegrationConfig,
 	saveRtkIntegrationConfig,
 } = await import("./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";
-import { compactPath } from "./techniques/path-utils.ts";
-import { applyWindowsBashCompatibilityFixes } from "./windows-command-helpers.ts";
-import { applyRewrittenCommandShellSafetyFixups } from "./rewrite-pipeline-safety.ts";
-import { applyRtkCommandEnvironment } from "./rtk-command-environment.ts";
-import { sanitizeStreamingBashExecutionResult } from "./tool-execution-sanitizer.ts";
-import { sanitizeRtkEmojiOutput } from "./techniques/emoji.ts";
-import { stripRtkHookWarnings } from "./techniques/rtk.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/index-test.ts

@@ -28,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);
@@ -52,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,
@@ -316,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,13 +1,13 @@
 import assert from "node:assert/strict";
-import { mock } from "bun:test";
 import { join } from "node:path";
+import { mock } from "bun:test";
 
 import { cloneDefaultConfig, runTest } from "./test-helpers.ts";
 
-const MOCK_AGENT_DIR = "C:/tmp/.pi/agent";
+const TEST_AGENT_DIR = "/tmp/.pi/agent";
 
 mock.module("@mariozechner/pi-coding-agent", () => ({
-	getAgentDir: () => MOCK_AGENT_DIR,
+	getAgentDir: () => TEST_AGENT_DIR,
 }));
 
 const { compactToolResult } = await import("./output-compactor.ts");
@@ -223,7 +223,7 @@ runTest("skill reads stay exact when preserveExactSkillReads is enabled for user
 	const result = compactToolResult(
 		{
 			toolName: "read",
-			input: { path: join(MOCK_AGENT_DIR, "skills", "example", "SKILL.md") },
+			input: { path: join(TEST_AGENT_DIR, "skills", "example", "SKILL.md") },
 			content: [{ type: "text", text: content }],
 		},
 		config,